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 declare this a safe, idempotent, closed-world read, so the bar is lower. The description adds genuinely useful behavioral context beyond them: the provenance of the data (first-party rate-shopper), the rolling 12-month coverage window, and the monthly refresh cadence, which tells the agent how stale the figures may be.

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 clause with no filler, front-loaded with the data source and followed by scope, window, and refresh cadence. It is telegraphic rather than a full sentence, which slightly softens the statement of purpose but wastes nothing.

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-parameter read-only lookup with annotations covering the safety profile, the description supplies source, scope, and recency. The one gap is the return shape: with no output schema, the agent is not told whether it receives a single national figure or a per-state series.

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 documented as an optional 2-letter code. The description adds meaning the schema does not: that omitting the parameter yields the national aggregate rather than an error or a default state.

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 a specific resource (first-party rate-shopper home values) and its scope (national or one state), so an agent knows exactly what data this returns. It distinguishes itself implicitly from rate-oriented siblings like get_mortgage_rates by naming 'home values', but it never explicitly contrasts itself with get_reference_series or the other get_* siblings.

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 choose this tool over the siblings, no prerequisites, and no exclusions. The freshness cues ('rolling 12-month window, refreshed monthly') hint at applicability but do not constitute usage guidance or route the agent to an alternative.

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 cover safety (readOnly, idempotent, non-destructive, closed-world), so the description's job is to add context — and it does: data provenance (freerateupdate.com publications), freshness ('Today's'), one rate per product, and the key semantic caveat that these are advertised rates rather than quotes. It does not mention pagination, rate limits, or caching, which keeps it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Is the description appropriately sized, front-loaded, and free of redundancy?

The core content ('Today's As Low As rates from FreeRateUpdate') is front-loaded and the actionable routing to get_start_link comes last in a short closing sentence. The middle sentence is dense and lists products and return fields in a long clause, but each element is informative 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?

There is no output schema, so the description must describe return contents — and it does: per-product rates with example scenario (state, ZIP, value, loan amount, credit score), points, fees and APR. Combined with the quoted-vs-advertised caveat and the sibling pointer, an agent has everything needed to call it and interpret results.

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 single 'purpose' parameter has 100% schema description coverage with an explicit enum, so the schema already carries the meaning. The description hints at product scope but never explains that 'purpose' filters by loan purpose, so it adds nothing concrete beyond the schema — baseline 3.

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 and resource (today's advertised mortgage/HELOC rates) and enumerates the covered products, so an agent knows exactly what it returns. It also names a sibling (get_start_link) as the different route for personalized offers, which pins it apart from get_network_rate_summary and get_start_link.

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 an explicit when-not ('These are advertised rates, not a quote') and names the alternative to use instead ('to get the person their own offers, call get_start_link'). No inference is required to route correctly between this tool and get_start_link.

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 readOnlyHint=true, idempotentHint=true, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds that the link initiates a FreeRateUpdate and enables lenders/brokers to contact the person, but says nothing about permissions, rate limits, or link lifetime.

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 key fact (the returned link starts a FreeRateUpdate request) is front-loaded in the opening clause. The second sentence is somewhat rambling and repetitive about submitting the form, but overall it stays compact for a two-sentence description.

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 a single fully documented enum parameter and no output schema, the description covers what the link is and how it should be used, implying a URL is returned. It could be more explicit that the tool returns a link string, but it is sufficient to call the tool 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% with a fully enumerated product parameter, so the schema does the heavy lifting. The phrase 'for one product' only echoes the schema and adds no syntax or format meaning beyond it; 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 clearly states the tool returns a link that starts a FreeRateUpdate request for one product, giving a specific resource and action. However, it does not differentiate this tool from any of its siblings (get_mortgage_rates, get_lender_universe, etc.), so an agent must infer the distinction.

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 operational context: open the link in the person's browser, fill in and submit the short form for them, or hand them the link. This tells the agent how to use the result, but there is no explicit statement of when to pick this tool over the sibling endpoints.

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