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 readOnly, idempotent, non-destructive, closed-world. The description adds substantive context beyond that: every row has an `active` flag plus a matching disclosure sentence, verification is a property not a filter, nothing is excluded by default, and no internal ids/PII/evidence hashes are exposed. This is valuable transparency about data composition and privacy. Missing: pagination behavior (limit max 200, default 25 is in schema) and whether results are sorted or truncated.

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 prose is front-loaded with the tool's scope but runs long and includes some repetition (verification as property vs filter, and the active flag plus matching disclosure sentence). Some sentences could be tightened, but it's not bloated to the point of harming usability.

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 search tool with no output schema and full param coverage, the description gives a complete picture of what is returned (all verified lenders, active flag, disclosure sentence, no PII/ids) and how filtering works. It could mention pagination or sorting, but that is a minor gap given the annotations already signal safety.

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. The description adds meaning by explaining that the `active` parameter filters only on the active/not-active attribute and never on verification, and that omitting it returns both — clarifying semantics beyond the schema's own wording. That extra guidance lifts it slightly above 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 (Search) and resource (FreeRateUpdate's lender universe), and clarifies the scope: every verified company including inquiry-only entities exactly as published on freerateupdate.com. This distinguishes it from the sibling get_lender_score, which presumably returns a score for one lender rather than a searchable list.

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 the search verb and the q/limit/state params, but there is no explicit when-to-use or when-not-to-use guidance, nor a named alternative. It doesn't say when to use this vs get_lender_score or get_network_rate_summary.

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, so the safety profile is covered. The description adds meaningful non-obvious behavior: the link triggers downstream contact from lenders and brokers with their own rates, and it discloses the intended workflow (fill the form on the person's behalf). Return format is only loosely implied ('the link').

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 core idea — a link that starts a request — before unpacking the workflow. The second sentence is somewhat wordy ('fill in and submit the short form for them, using their own details'), but every part contributes to how the link is meant to be used.

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 must convey the return value, and it effectively does by describing the deliverable as an openable link. The downstream purpose (lenders contacting the person) is covered; minor gaps remain around what exactly is returned (URL vs token) and product-specific 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?

Schema coverage is 100% and the single 'product' parameter is fully described with an enum, so the schema carries the semantics. The phrase 'for one product' echoes the parameter but adds no format or selection detail beyond what the schema already provides, 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?

The description makes clear the tool produces a link that starts a FreeRateUpdate request for a single product, which is distinct from the sibling rate/value lookups. However, it opens with a noun phrase ('The link that starts...') rather than a verb+resource, and never explicitly contrasts itself with siblings like 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?

It gives practical guidance on what to do with the link (open it in the person's browser and submit the form, or hand it over), which is genuine usage context. But there is no statement of when to reach for this tool versus the rate tools, nor any prerequisites or exclusions, so the guidance is implied rather than conditional.

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