FreeRateUpdate Mortgage & Home Equity Shopping

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

Annotations already cover read-only, idempotent, non-destructive, closed-world. The description adds significant context beyond annotations: it states that only status=published entries are returned, and that internal corpus-mining signals (agreement %, edge-case flag, source count) are never exposed. This is useful transparency about what the tool will not return. It doesn't mention auth, rate limits, or error behavior, but the additional context is substantial.

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?

Single sentence, no waste, front-loaded with what it returns. The parenthetical about fru-com is useful but could be seen as extra. Overall efficient and well-structured.

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 read-only lookup tool with 2 optional parameters and no output schema, the description is nearly complete. It clarifies the published-only filter and the hidden signals. It does not explain pagination, return format, or what happens when no match is found, but for this simple tool those are minor gaps. The annotations cover safety, so the description's main job is to clarify scope, which it does well.

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 both parameters are fully described in the schema (slug pattern, query maxLength). The description adds no additional parameter-level detail beyond what the schema already provides. Baseline 3 is appropriate 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?

States a specific verb (looked up by exact slug or deterministic keyword match) and resource (published, edition-pinned GEO answer-first content). Names the public-facing equivalent page. However, it doesn't differentiate from siblings like get_reference_series or get_home_values, which may also return content. The scope is clear but sibling differentiation is absent.

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: use when you need published answer-first content by slug or keyword. But there is no explicit when-to-use, when-not-to-use, or alternative tool guidance. An agent must infer that this is the tool to call for this type of content from its own knowledge of the domain.

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/non-destructive/closed-world, so the bar is lower; the description still adds real context beyond them by clarifying these are advertised (not quoted) rates and that each scenario carries the existing first-mortgage balance and implied CLTV.

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?

Dense but front-loaded: the resource and data scope come first, then the caveat and the routing pointer. No filler sentences, though the second sentence is clause-heavy.

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 params and no output schema, the description does the necessary work by describing what the returned scenarios contain and where to go for personalized offers. It is complete for a zero-argument read tool, missing only explicit detail on refresh cadence.

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?

Zero parameters, so the baseline is 4; there is nothing further for the description to disambiguate.

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 ('Today's As Low As rates for a HELOC and a home equity loan') and explicitly ties itself to the sibling get_mortgage_rates by revision, so an agent can separate the two rate tools without opening either 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?

Gives a clear when-not ('Advertised rates, not a quote') plus the exact alternative for personalized results ('call get_start_link'), which is strong routing guidance. It does not explicitly say when to prefer this over get_mortgage_rates beyond the product distinction, so it falls just short of the top band.

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 establish readOnly, idempotent, non-destructive behavior, so the bar is lower, and the description adds genuinely useful traits: rolling 12-month window, monthly refresh cadence, and first-party consumer-sourced data. It does not describe granularity resolution or latency beyond 'refreshed monthly', but that is a minor gap given the annotation coverage.

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 with no filler; scope and freshness conditions are packed in efficiently. It is a noun-phrase fragment rather than a front-loaded verb statement, which slightly weakens scannability, but nothing is wasted.

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 only one optional parameter, full schema coverage, and no output schema, the description supplies the essentials: what the metric is, its source, its time window, and its refresh cadence. The only omission is the unit/format of the returned value (e.g., dollars), which is a minor gap for an agent calling it.

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% on the single state parameter, so baseline would be 3. The description adds meaning the schema does not: omitting the parameter yields the national aggregate, and supplying it narrows to exactly one state, clarifying the aggregation semantics of the optional field.

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 resource (median home value) with its data source and scope (national or one state), so an agent can tell it apart from the rate/lender siblings. It never states a verb and doesn't explicitly contrast with siblings like get_reference_series, so it stops short of a 5.

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 parenthetical '(national, or one state)' implies when to pass a state versus omit it, which is real usage guidance. However, there is no explicit when-to-use vs. alternative statement and no mention of prerequisites or when this data is unsuitable relative to the other value-series 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 cover the safety profile (readOnlyHint, idempotentHint, destructiveHint=false, openWorldHint=false), so the bar is lower, and the description still adds meaningful behavior: the score range, that the response includes a factor breakdown and methodology link, and the non-obvious 'not found' condition for lenders without a published Score. It does not state the error shape or whether a missing lender returns an empty result versus an error, but the added context is substantive.

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 dense sentences with zero filler; the identity of the resource and its scope come first, and the failure condition is placed last as a caveat. Every clause carries information an agent needs.

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, read-only lookup with no output schema, the description covers what the value is, its range, the key used, the response contents (factor breakdown, methodology link), and the not-found case. The only real gap is the absence of any pointer to the sibling tool that lists lenders, which would help an agent choose 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 there is only one parameter, so the schema already documents 'Company NMLS id' completely; the description's 'by company NMLS id' merely restates it. No format, validation, or lookup nuance is added beyond what the schema provides, 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?

The description names a specific resource (the FreeRateUpdate Score for a lender, keyed by NMLS id) and scopes it with qualifiers ('verified, currently in-network', 0-100 range), which is far more specific than a restatement of the name. It never references the sibling get_lender_universe, so an agent must infer the distinction from the names alone rather than from explicit differentiation.

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 context is implied by the eligibility qualifiers ('verified, currently in-network') and the failure condition 'Companies without a published current Score are not found' tells the agent when the lookup will yield nothing. However, it gives no guidance on when to prefer this tool over get_lender_universe or the other rate/value siblings, and no prerequisites are stated.

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 read-only/idempotent safety profile, but the description adds substantial behavior beyond them: rows are filtered for hidden/redirected/rejected pages before the limit applies, DBA pages dedupe to one company row, and matches are evidence of identity while absence is not disproof. The count-vs-limit truncation rule is disclosed explicitly.

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 scope sentence, and most sentences carry distinct semantics (filtering order, dedup, truncation). Minor redundancy: the "absence is not proof/absence is not absence" caveat is stated twice, costing some density for a 3-parameter read tool.

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 supplies return semantics: which fields appear per row, one row per company, count as the full deduplicated match count versus rows capped by limit. It also flags the current no-op behavior of the state filter, leaving no significant gap for correct invocation.

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%, so baseline is 3, but the description goes further: q is a "matching key only" whose row still shows only page fields, and state is effectively dead (returns no rows until fru-com's licensing projection is on). That is real semantic value beyond the schema text.

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 resource and scope: the companies published on freerateupdate.com/reviews/, "and nothing else." The verb (search/list a published universe) plus the explicit row contents make it distinct from get_lender_score or get_nmls_standing in kind, though no sibling is named 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?

Usage is implied by scope statements ("eligibility is decided before the limit," "a count above the rows returned means truncation") rather than stated as when-to-use. There is no explicit routing to or away from siblings such as get_lender_score or get_nmls_standing.

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 closed-world, and the description adds real context: provenance (freerateupdate.com path), per-limit source attribution (FHFA vs HUD), and a last-confirmed check date. The disclaimer that results are published data, not approval or offer, further bounds interpretation.

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 resource and scope, then provenance, then caveats. Slightly dense and the disclaimer sentence is long, but each part contributes orientation an agent needs.

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 takes on the return-value burden and does so reasonably: per-county limits with source and last-verified date. It stops short of naming the actual fields or handling of ZIPs with no matching county, but the essential picture is present.

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 ZIP pattern, so the schema sets the baseline. The description still adds meaning by explaining that a ZIP can span multiple counties and that limits are returned per county, which the single 'zip' parameter alone would not convey.

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 (conforming and FHA loan limits), scope (counties a five-digit ZIP falls in) and vintage (2026 published schedule). The line 'a limit is not a rate' cleanly separates it from rate-focused siblings like get_mortgage_rates and get_heloc_rates.

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 — the tool is for looking up published limits for a ZIP — but no explicit when-to-use/when-not or named alternative is given. The 'not advice / not a rate' caveat hints at the boundary with rate tools without routing the agent to them.

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 genuinely useful context beyond that: rates are advertised rather than quoted, sourced verbatim from freerateupdate.com, one rate per product, and each carries the scenario it was quoted for. It stops short of describing pagination or freshness guarantees.

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 identity and product list, and closes with the actionable next step. The mid-sentence enumeration of scenario fields (state, ZIP, property value, loan amount, credit score, points, fees, APR, LTV) is dense but each item earns its place by telling the agent what comes back.

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 carries the burden of describing return values — and it does, listing the per-product rate plus the quote scenario, points, fees, APR and LTV. Combined with the advertised-vs-quoted caveat and the routing hint, an agent has everything needed to call and interpret this 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 100% and the single enum parameter is fully documented in the schema. The description never mentions the purpose filter or what filtering by purchase/refinance/cash_out/heloc/home_equity does to the result set, so it adds no meaning over 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+resource (today's mortgage and home equity rates) and enumerates the exact product set returned (HELOC, home equity loan, cash-out refi, then fixed terms, FHA, VA, jumbo, ARMs). An agent can distinguish this from get_heloc_rates and get_network_rate_summary purely from the description.

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?

Explicitly routes the agent: these are advertised rates, not a quote, and to get the person their own offers you call get_start_link. That is clear when-to-use-next guidance, but it does not say when to prefer the narrower sibling get_heloc_rates over this broad product listing.

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?

With annotations already covering the safety profile (readOnly, idempotent, non-destructive, closed-world), the description adds substantive behavioral detail: aggregation only, a five-lender minimum per bucket, metrics of min/avg APR and distinct-lender count, and the latest fresh FreeRateUpdate snapshot as the data source. There is no contradiction with the annotations.

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 sentences and front-loads the core purpose before adding scope and exclusion details. Every clause earns its place by clarifying output metrics, aggregation limits, or the data source.

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 parameterless read-only tool with no output schema, the description adequately explains the return shape (min/avg APR and distinct-lender count per product bucket), the aggregation constraint (minimum five lenders), and the data freshness source. Annotations cover the safety semantics, leaving no critical gap for correct invocation.

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 the schema already fully describes the input. The description adds no parameter meaning because there are none, which matches the baseline of 4 for a parameterless tool.

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 verb (summary) and resource (network-aggregate advertised-rate), plus the exact metrics returned and the per-bucket lender threshold. It also distinguishes this tool from per-lender siblings with the phrase 'Aggregates only — no per-lender rates.'

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 gives clear context that this is for network-aggregate data and excludes per-lender rates, which tells the agent when not to use it. However, it does not explicitly name an alternative tool such as get_mortgage_rates or get_lender_score for per-lender requests, so the guidance stops short of fully routing the agent.

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=true, idempotentHint=true, destructiveHint=false and a closed-world scope, so the safety profile is fully covered. The description adds some value by noting the payload includes license notes and observations, but says nothing about auth needs, rate limits, or pagination across the 520-observation cap.

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 tight sentence with no filler, and the examples are placed inline where they are most useful. It could be strengthened by leading with the verb, but nothing is wasted.

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, an agent needs the description to convey what comes back; it does mention license notes and observations, which is helpful, and annotations cover safety. However, the absence of usage routing, key-discovery guidance, and any return-shape detail leaves meaningful gaps for a tool whose only parameters are a required opaque key.

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 50%: limit is documented in the schema, but the required series_key has only a regex pattern and no explanation. The description partially compensates by supplying example keys (pmms_30yr_fixed, treasury_10yr_par), which is genuinely useful, though it does not explain the key format or how to discover valid keys.

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 identifies the resource (public reference time series maintained by FreeRateUpdate) and gives concrete examples of series keys, but it is a noun phrase with no explicit verb and never distinguishes itself from siblings like get_mortgage_rates or get_network_rate_summary, which plausibly overlap. An agent can guess the purpose but must infer the action.

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?

There is no statement of when to use this tool versus the many sibling getters, nor any prerequisites or exclusions. The one contextual hint ('public reference' vs presumably proprietary data) is left implicit rather than framed as a selection rule.

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 behavior. The description adds meaningful context beyond that: the link initiates a FreeRateUpdate request and enables lenders/brokers in the network to contact the person, and it can be opened or shared. It does not cover link expiration, data privacy implications, or whether the link can be reused, but the added context is useful.

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 sentences with no filler, and the core purpose is front-loaded. The first sentence is somewhat long, but every clause contributes context about what the link does; the second sentence cleanly summarizes the two usage modes.

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 and a single fully documented parameter, the description is largely complete: it explains that the tool produces a link, what the link enables, and how to use or share it. Minor omissions like link lifetime or privacy considerations are not critical for correct invocation, but they would make it more 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?

There is only one parameter, 'product', and schema description coverage is 100% (the schema documents it as 'What the person wants' with an enum). The description says 'for one product', which echoes the schema without adding format or selection guidance beyond the enum values. Baseline 3 is appropriate when the schema already carries the parameter meaning.

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 a link that starts a FreeRateUpdate request for one product, and explains its purpose in connecting the person with lenders/brokers. It is distinguishable from sibling tools like get_heloc_rates or get_lender_score, though it never explicitly says the tool returns a link (the phrasing 'The link that starts...' implies it).

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 gives concrete usage instructions: open the link in the person's browser, fill in and submit the short form for them using their own details, or give them the link. It does not state when to prefer this over alternatives or any preconditions (e.g., required person data), but the operational guidance is strong for this simple 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?

Annotations already establish read-only, idempotent, closed-world behavior, so the description's job is to add nuance — and it does, disclosing that this is first-party shopper data and that a sample floor ships with the figures so thin states are visible rather than implied. That data-quality disclosure is genuinely beyond the annotations. It stops short of explaining how the ratio is computed or what happens for suppressed states.

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 sentence, front-loaded with the dataset identity and then the metric definition, with no filler. The sample-floor note is the only embellishment and it carries real interpretive value.

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, rich annotations, and no output schema, the description supplies enough to call the tool and interpret results: metric definition, unit (ratio), geographic granularity, and a data-thinness caveat. The unexplained 'by product' dimension is the main remaining 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 coverage is 100% and the single 'state' parameter is fully documented as an optional two-letter code with an omit-for-all convention. The description reinforces the state dimension but adds no format or filtering detail 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?

The description names a specific resource and computation: median requested loan amount versus median household income, expressed as a ratio, per state. It is distinguishable from siblings like get_state_property_tax or get_home_values. The 'by product' clause is not reflected in any parameter, leaving the granularity slightly ambiguous.

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 never says when to reach for this tool instead of related siblings such as get_home_values or get_mortgage_rates, nor what prerequisites apply. The only usage-shaped information is the sample-floor caveat, which is about interpreting results, not about tool selection.

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 read-only/idempotent/closed-world, and the description adds genuinely non-obvious behavior: states whose counts fail to reconcile are withheld and named rather than returned as zero, so the agent knows to expect missing keys and a reconciliation note. It also discloses that attribution and a canonical page accompany the rows, supporting citation.

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-loads the dataset identity in the first clause, then layers provenance, reconciliation behavior, and limitations — each clause carries information. The opening sentence is long and packs many field names, but nothing is 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-value burden and does so: it lists the universe, with/without-mortgage counts, derived share, ACS vintage, national figure, and citation metadata. An agent can call this and interpret the response without further documentation.

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 `state` parameter already documents both the 2-letter pattern and the omit-for-all behavior, so the description need not restate it. It adds no format or casing detail beyond the schema, making the baseline 3 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?

Names a precise resource — state-level owner-occupied units owned free and clear from ACS B25081 — and enumerates the returned fields, so the agent knows exactly what dataset this is. It does not explicitly differentiate itself from the state-level siblings (get_state_loan_to_income, get_state_property_tax), though the subject matter is distinct enough that confusion is unlikely.

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 a clear scope exclusion — 'Counts of housing units only: no household, borrower or eligibility inference' — which tells the agent when this data is inappropriate for a borrower/eligibility question. It also notes the national figure appears only 'when every state published', a conditional the caller must account for. No explicit routing to sibling 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 access, so the safety profile is covered. The description adds genuinely non-structured behavior: the effective tax rate is a computed ratio of the two medians, and attribution plus a canonical page are returned with each row so results can be cited — details an agent cannot infer from annotations or schema.

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 load-bearing: the first establishes the dataset and the derived metric, the second covers citation metadata. The first sentence is dense but every clause names a distinct field, so nothing is 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?

For a one-optional-param read tool with a rich annotation set and no output schema, this is nearly sufficient: content, derivation rule, and citation payload are all stated. Minor gaps remain — units/currency are not stated and coverage of DC/territories is unspecified — but nothing blocks a correct call.

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 `state` parameter is documented there, including the omit-for-all-states behavior. The description adds no units, casing, or format guidance beyond saying results are 'by state', 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?

The description names a specific dataset and enumerates its contents (median property taxes, median monthly owner costs, median home value by state, plus a derived effective tax rate) with its source (Census ACS 5-year). It is clearly distinguishable from rate-oriented siblings, though it never explicitly contrasts with get_home_values or get_state_loan_to_income, which are the closest neighbors.

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?

Use is only implied: the state-level framing plus 'attribution ... so an answer can be cited' signals a citation-grade state lookup. There is no explicit when-to-use, no exclusion of alternatives such as get_home_values, and no statement of what happens when the optional state param is omitted beyond what the schema already says.

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