Safe Rate

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is covered. The description adds genuine context beyond that: the geographic constraint (US), the aggregation level (area rather than property), and the specific data sources composing the result (FEMA NRI, flood zone). It says nothing about behavior on unknown/unmatched locations or data freshness, which is the remaining gap.

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

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

Two sentences, front-loaded with purpose, followed immediately by the scope caveat. The enumerated output list is dense but each item is a distinct hazard/insurance dimension rather than filler, and the negative scoping line earns its place by preventing misuse.

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 by naming the five result categories the caller will receive, plus the US-only and area-level constraints. What remains unstated is the shape of the response (scores vs. narrative, units) and failure behavior for unparseable locations, which keeps it from being fully complete for a two-parameter lookup.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with both parameters documented in-schema including accepted location formats and the effect of property_value on dollar estimates. The description itself contributes only the word "US" as a constraint on the location parameter and does not elaborate on parameter behavior beyond the schema. Baseline 3 is appropriate when the schema carries the parameter burden.

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 opens with a specific verb and resource ("Assess hazard exposure and insurance conditions for a US location") and then enumerates the concrete outputs: FEMA National Risk Index score, flood-zone coverage, mortgage flood-insurance requirement, wildfire/earthquake exposure, and local insurance-market conditions. The closing line "Describes the area, not a specific property" disambiguates it from any property-level sibling. An agent knows exactly what this returns without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives a clear scope boundary (area-level, not a specific property) and a geographic restriction (US locations only), which functions as a when-not condition. It does not name an alternative tool for property-level or non-US needs, and no siblings in the list (lenders, treasury, quotes) are referenced for routing, so it stops short of full when/when-not/alternatives guidance.

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

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

The annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is covered. The description adds genuinely useful context beyond that: the return is plain text embedding an as-of date, canonical URL, license, and citation notice. It also discloses a domain caveat that rate index pages are indicative, refreshed daily, and not a borrower-specific quote, which 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?

Three compact sentences, front-loaded with the action and resource, then return content, then the most decision-relevant caveat. No filler and nothing repeated from the schema or annotations.

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, but the description compensates by describing exactly what the response contains (plain text with as-of date, canonical URL, license, citation notice) and its reliability limits. Combined with annotations covering safety and a fully documented single parameter, an agent has everything needed to call it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There is exactly one parameter with full schema description coverage (100%), including format examples, so the schema carries the burden. The description only restates 'document id' without adding syntax or lookup guidance beyond what the schema already provides, making the baseline 3 appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb and resource: fetch one Safe Rate published page, scoped by document id. That is enough to separate it from sibling tools like search (which supplies the ids) or get_market_context, although it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: 'by its document id' hints the id comes from search, and the schema spells that out with examples. There is no explicit statement of when to prefer this tool over get_market_context or search, and no when-not-to-use guidance.

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

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

Annotations already cover readOnly, idempotent, non-destructive and closed-world, so the safety profile needs no restating. The description adds genuinely non-structured context: the rankings come from public federal HMDA filings and 'placement cannot be purchased,' which tells the agent the ordering is data-derived rather than sponsored. It also frames the result as a non-personalized starting list, though it says nothing about result size or coverage gaps for thin markets.

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, no filler, and the scoping information (what is listed, where, sliced how) is front-loaded ahead of the provenance and disclaimer clauses. Each sentence contributes a distinct fact.

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 four-parameter, read-only lookup with no output schema, the description covers purpose, geography, slicing, and data provenance adequately. The one remaining gap is that it never sketches what a lender entry contains (name, rank, volume), which matters because there is no output schema to fall back on.

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 schema already spells out the loan_type/institution_type mutual exclusivity and the conventional-loans default. The description's 'sliced by loan type OR by institution type' and 'metro area or a whole state' echo the schema rather than extend it. Baseline 3 is appropriate when the schema carries the parameter burden.

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 opens with a specific verb and resource ('List the lenders ... publishes rankings for') and bounds the geography ('metro area or a whole state') and the two slicing modes. An agent can immediately tell this returns a ranked lender list rather than a single-lender profile. It stops short of naming a sibling such as research_lender to make the boundary explicit.

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 'This is a starting list, not a recommendation for a specific borrower,' which tells the agent the output is a discovery step. However, it never says when to prefer this over research_lender or get_market_context, nor does it state prerequisites (e.g., that a location is mandatory and must resolve to a US market).

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false, and openWorldHint=false, so the safety profile is fully covered and the description needn't repeat it. The description adds genuine context beyond that: the data provenance (HMDA filings) and the US-only scope. It doesn't state latency, rate limits, or what happens when a location cannot be resolved, which is the main residual gap.

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

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

Two sentences, front-loaded with the verb and the returned metrics, followed by the use case. Every clause carries information; no filler or repeated annotation content.

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?

No output schema exists, and the description compensates by enumerating the returned fields, including the national percentile framing. For a read-only, single-parameter lookup with rich annotations, nothing an agent needs in order to call it correctly is missing.

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?

With a single parameter at 100% schema description coverage, the schema already specifies accepted forms (ZIP, city + state, county + state) and examples. The description's only addition is the 'US location' constraint, which is meaningful because the schema would otherwise accept any string or number. That is a modest but real contribution, so it sits at the high end of the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (get local housing-market context) and enumerates the concrete outputs: median home value with national percentile, median rent, appreciation, and HMDA mortgage activity. This makes it distinguishable in substance from assess_property_context or find_lenders_in_market, but it never names a sibling tool to route against.

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 use case: 'answer whether a price or a market is typical,' which tells the agent the question type this tool serves. It stops short of stating when NOT to use it or which sibling to pick for property-level versus market-level questions.

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), and the description adds real context on top: the required auth scope, the fact that building an application is distinct from applying for a loan, and a privacy guarantee that identity details like SSNs are never returned. That privacy statement is behavioral information an agent cannot obtain from the annotations or the empty 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?

Front-loaded with the auth requirement, then purpose, then returned content and the privacy caveat — every clause contributes. The single run-on sentence with stacked parentheticals and the trailing 'and so on' make it slightly less crisp than it could be.

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 itself and does so by naming the scenario fields, progress, and status. Combined with the auth scope and privacy guarantee, an agent has everything needed to call a zero-parameter read 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?

The tool takes zero parameters, so there is nothing for the description to disambiguate — the baseline of 4 applies. Nothing in the text misleads about inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Read the shopper's own Safe Rate Universal Application') and immediately scopes what that object is (the application the shopper builds to share with lenders, not a loan application). The subsequent clauses enumerate the contents returned — loan scenario fields, progress, status — so an agent knows exactly what it gets, and the read/start/update split against siblings is clear from the wording.

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 precondition ('Requires the shopper's Safe Rate sign-in (scope poppy:read)') and implies usage for the signed-in shopper's own record. It does not explicitly point to start_my_application or update_my_application as the write-side alternatives, so the routing is inferred from the verb rather than 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 declare readOnly, idempotent, and non-destructive, so safety is covered. The description adds genuinely non-obvious behavior beyond that: results are auth-gated by scope poppy:read, and offers from Safe Rate Mortgage are withheld until the affiliated business disclosure is accepted on saferate.com — an agent who does not know this would misreport missing offers as an error.

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 precondition before the payload, then the disclosure caveat. Every sentence carries a distinct fact, though the disclosure sentence is dense enough that a reader may need to re-read it before acting.

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 parameters and no output schema, the description carries the full burden of describing returns, and it does so by naming the offer fields (rate, APR, points, product). Combined with the auth precondition and the partial-results rule, an agent has everything needed to call it and interpret a thin response 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?

The tool takes zero parameters, so there is no parameter semantics to explain and the baseline is 4. The description correctly avoids inventing filtering or pagination inputs that the schema does not contain.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: list quote requests the shopper sent to lenders plus the returned offers (rate, APR, points, product). The possessive 'my' scope separates it from market-level siblings like get_market_context, but it never names get_quote_estimate or track_quote_estimate, so an agent must infer the estimate-vs-actual-quote boundary itself.

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 sign-in prerequisite (scope poppy:read) tells the agent when the call will succeed, and 'the quote requests the shopper sent' implies the authenticated-shopper context. However, there is no explicit when-to-use versus get_quote_estimate, track_quote_estimate, or get_my_application, which is the most likely sibling confusion for this 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 declare readOnlyHint=true and destructiveHint=false, so the description is not carrying the safety burden. It does add genuinely non-derivable behavior: results are non-binding Safe Rate estimates rather than lender quotes, and the response contains an estimate ID the borrower can use to track changes later. It does not mention the ok:false / missing-parameter return path that the schema documents, but that is a schema-side disclosure.

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

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

Two sentences, zero waste, with the scope and PII constraint front-loaded ahead of the estimate-vs-quote caveat. Every clause carries information an agent needs before calling.

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 8 optional parameters fully documented in the schema and no output schema, the description covers the essentials: what is returned conceptually (estimates plus an estimate ID) and what the numbers legally are. It stops short of describing the shape or richness of the rate results, which an agent might want given there is no output schema.

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%, including defaults, enum values, and elicitation behavior for location and purchase_price, so the schema does the heavy lifting. The description adds no parameter-level meaning beyond the schema — no guidance on which combinations matter or how inputs affect pricing.

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 — 'get live mortgage rate estimates for any US location' — plus the PII-free condition that defines this tool's scope. It implies a boundary with the sibling get_my_quotes (this returns estimates, not the borrower's own quotes) and with track_quote_estimate (the returned estimate ID is what feeds tracking), but it never names those siblings explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: the reader can infer this is the anonymous pre-application pricing path and that the returned estimate ID routes to tracking, but there is no explicit 'use this when X, use get_my_quotes when Y'. No prerequisites or exclusion conditions are stated, so the agent must infer selection against a large sibling set.

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

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

The annotations already declare read-only, idempotent, closed-world, non-destructive behavior, so little is left to disclose. The description adds the domain caveat that an I bond's headline rate lasts only six months while the fixed component persists, which is interpretive context rather than behavioral disclosure, and it says nothing about pagination or response shape.

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

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

Two sentences, front-loaded with the core resource and its components, then the optional extras. The closing note on the six-month headline rate is a slight aside but earns its place by steering the agent toward the fixed component.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of describing returns, and it does list the rate types and optional series an agent will get back. For a two-optional-parameter read tool this is close to sufficient, though it omits anything about historical range limits.

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 description's mention of 'how many bonds the public holds and how many are being sold' merely restates the public_holdings and sales enum meanings already documented in the schema. It adds almost no meaning beyond what the structured field provides, 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 verb and resource (savings bond rates) and enumerates the precise data covered: Series I composite, its fixed and inflation components, and EE rates by issue cohort. That clearly separates it from siblings like value_savings_bond (valuation) or get_treasury_curve, though no sibling is named explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

It signals that holdings and sales figures are opt-in extras and clarifies that historical as well as current rates are available, which implies usage. However, it never states when an agent should call this instead of value_savings_bond or get_treasury_rate_history.

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

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

Annotations already declare readOnly, idempotent, non-destructive and closed-world, so the safety profile is covered. The description adds genuinely non-redundant behavior: the required auth scope and the critical clarification that this tool never performs the share, which prevents an agent from over-promising an action.

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 short sentences, front-loaded with the hard requirement and followed by the key behavioral caveat and the return value. Nothing is repeated and no sentence 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?

For a one-parameter read tool with no output schema, the description covers the auth prerequisite, the non-obvious limitation, and the nature of the returned link. It stops short of saying whether the link expires or is bound to a session, a minor gap given the tool's simplicity.

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 'lender' parameter is already documented in the schema as the lender to mention in the hand-off. The description adds no further syntax, format, or defaulting details beyond that, 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 uses a specific verb-and-resource framing ('Returns the link where the shopper reviews and shares it themselves') that tells an agent exactly what comes back. It also carves out a boundary ('Does NOT share anything'), which separates it from any implicit 'share' behavior an agent might assume, though it never names a sibling tool.

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?

Preconditions are stated explicitly: the shopper's Safe Rate sign-in with the poppy:read scope, plus the note that actual sharing always requires the shopper's own click on saferate.com. That's clear when-and-how context, but no explicit alternative tool or exclusion path is offered.

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 behavior, so the safety profile is covered. The description adds genuine context on top: default inclusion set, the meaning of omitting the date, and non-trading-day behavior. Auth requirements and response size/pagination are not discussed, but they are minor for a read-only curve lookup.

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 front-loaded sentences carry the payload, with the caveat sentence placed last. Every clause does work: scope, optional outputs, default behavior, and a domain disambiguation.

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 zero-required-parameter read tool with no output schema, the description tells an agent what comes back and how defaults behave, which is sufficient to call it correctly. The one real hole is the mismatch between the advertised par/money-market curves and the include enum, which leaves the agent uncertain how to request them.

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 schema descriptions already explain the date format, the default include set, and every enum value, so the baseline is 3. The description adds little beyond restating those fields, and it introduces a discrepancy: it advertises a 'par curve' and 'money-market curve' on request, but neither appears in the include enum, which could send an agent looking for options that do not exist.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (get the U.S. Treasury yield curve) plus the exact scope (a single day) and enumerates the curve variants returned. The single-day framing implicitly separates it from get_treasury_rate_history, and the closing note 'Treasury yields are not mortgage rates' pins the domain against mortgage-related 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?

Gives concrete when-to guidance: 'Omit the date for the most recent published day, which is what you want on a weekend or holiday.' It does not name sibling tools or state exclusions (e.g., when to reach for history or a specific security instead), so it stops short of full routing guidance.

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

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

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false, and destructiveHint=false, so the safety profile is covered and the description need not repeat it. The description adds provenance (monthly Treasury statement) and interpretive context showing the two figures differ by trillions and that debt held by the public excludes intragovernmental trust-fund holdings. It stops short of return shape, units, or update lag, which are the remaining behavioral gaps.

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, front-loaded with the primary purpose and the enumerable payload, then a second sentence whose whole job is to prevent the most likely analytical error (confusing the two headline figures). Slightly dense with the colon-list and the em-dash gloss, but no sentence 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?

For a read-only, two-optional-parameter tool with no output schema, the description covers the essential ground: what series is returned, that it comes from the monthly statement via the schema's month-end rule, what the optional flag yields, and how to read the two headline numbers. Units and any lag in the published statement are the only notable omissions, and an agent can still call it correctly without them.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters (the 'on' date and include_strips) are already fully documented, which sets the baseline at 3. The description does add a small amount: 'plus the STRIPS float on request' signals that the STRIPS figure is the opt-in extra gated by include_strips, and it glosses what the flag unlocks, but it introduces no date-format or default detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

Names a specific verb (Get) and a specific resource (U.S. federal debt from the monthly Treasury statement), then enumerates the actual data elements returned: debt held by the public, total public debt outstanding, composition, and STRIPS float. That resource is plainly distinct from the other treasury siblings (curve, index, rate history, security), so an agent can route without opening a schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage is only implied: an agent infers this is the tool for headline debt figures, but there is no explicit when-to-use, no statement of when another tool (e.g. get_treasury_curve for rates, get_treasury_index, list_treasury_securities) is the better choice, and no mention of what question this cannot answer. The explanation of the two headline figures helps interpretation of results rather than selection of the 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 declare readOnly/idempotent/non-destructive, so the safety profile is covered. The description earns credit beyond that by flagging the semantic trap that a rising level usually means yields fell, and by disclosing provenance — constructed by Safe Rate, not an official Treasury statistic — which matters for how an agent cites the data. Rebalance-date-only constituents is also surfaced in the schema, not repeated here.

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

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

Three tight sentences, front-loaded with what the tool returns, then the enumeration and the critical total-return caveat. No filler and no repetition of schema detail.

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 zero required parameters, full schema coverage, and no output schema, the description does the needed work of explaining what comes back (levels, listing, fund comparison). It could be slightly stronger by indicating the shape of a single-index response versus the listing, but nothing essential for correct invocation is missing.

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 all five parameters are already documented with patterns and examples. The description adds only the no-code listing behavior, which reinforces the optionality of 'code'; it adds nothing about 'on', 'since', 'include', or 'constituents_on' beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource (Treasury total-return indices) and enumerates the coverage space — maturity buckets, bills, TIPS, floating-rate, aggregate. The explicit 'TOTAL RETURN levels, not yields' line separates it cleanly from get_treasury_curve and get_treasury_rate_history, which an agent might otherwise confuse it with.

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 operational rule — 'call with no code to list every index and discover the codes' — which tells the agent how to bootstrap from an unknown code. It implies the alternative yield tools by contrast but never names get_treasury_curve or says when not to use this one, so routing is inferred rather than 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 establish readOnly, idempotent, non-destructive, and closed-world, so the safety profile is covered. The description adds real behavioral context not in annotations: data coverage begins 2008-09-02 and results are one row per trading day, warning about row volume. It does not describe the returned columns, but no output schema exists to lean on.

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?

Four short sentences, front-loaded with purpose, then usage, then the coverage constraint and volume warning. Every sentence carries distinct information and none repeats another.

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 three-parameter read tool with a fully described schema, no output schema, and complete annotations, this covers purpose, coverage window, granularity, and a range-size caution. The only gap is the shape of the returned rows beyond row-per-trading-day granularity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, and the description's curve descriptions largely restate the enum meanings in the schema. The added value is limited to restating the 2008-09-02 floor and the default curve behavior, which the schema also states. 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 opens with a specific verb and resource: "Get a history of U.S. Treasury yields between two dates," and enumerates the three curve variants. It does not explicitly distinguish itself from the sibling get_treasury_curve, though the phrase "one row per trading day" and "how have rates moved" implies the historical series rather than a point-in-time curve.

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 names the question shape it answers ("Use this for 'how have rates moved' questions") and gives a concrete operating constraint ("Keep ranges tight — a decade is thousands of rows"). It stops short of naming an alternative tool for single-date curve lookups, which would have made routing unambiguous.

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 read-only, idempotent, closed-world operation, so the safety profile is covered. The description contributes the returned data surface (history plus analytics plus outstanding amounts), but says nothing about result size, pagination, partial-data behavior, or what happens when a CUSIP is unknown. The heavy-volume warning lives in the schema, not here.

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, front-loaded sentence opening with the verb and resource, then the payload, then the constraint. It is long but each clause maps to a distinct piece of information; minor compression would be possible 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, the description carries the burden of telling the agent what comes back, and it does so across all the major return categories. Missing pieces are minor for a read-only lookup: no mention of error behavior for invalid CUSIPs or result volume, though the latter is covered in the parameter schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all three parameters are already documented, including the summarize/history tradeoff and the outstanding_on date semantics. The description's CUSIP-versus-description sentence adds a modest amount of meaning by clarifying what the required parameter accepts, but nothing beyond the schema 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?

Names a specific verb and resource ("Look up one Treasury security by CUSIP") and enumerates the returned content: terms, price history, duration/convexity/DV01/key-rate durations, TIPS and floater analytics, amount outstanding. It does not, however, distinguish itself from the adjacent list_treasury_securities or price_treasury_security tools, so an agent must still infer why this one rather than those.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The closing sentence gives a real usage constraint — supply a CUSIP, not a descriptive phrase like "the current 10-year" — which steers the agent away from a natural but unsupported query form. Beyond that, there is no explicit when-to-use guidance and no named alternative for the overlapping list/price siblings.

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 behavior, and the description's hints about the 'full outstanding and priced universe' mostly restate what the schema already says (hundreds of rows for 'outstanding'). It adds the default-day semantics implicitly via 'omit the date for the most recent day with prices', but nothing about ordering, pagination, or gaps on days with no prices.

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

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

Front-loaded with the verb and resource, then a single colon-delimited list of modes; no filler sentences. The one long sentence is dense and could be split for readability, but every clause carries information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With three optional parameters, a fully documented schema, and no output schema, the description covers what the tool returns at a conceptual level (on-the-run by tenor, full universe, priced CUSIPs) and the default date behavior. It is nearly complete; only result ordering/shape detail is absent, which is minor for a read-only listing 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 coverage is 100%, so the baseline is 3, but the description goes further by mapping each enum option to a user-facing intent ('which security is on-the-run for each tenor', 'the full outstanding and priced universe', 'just the priced CUSIPs'), which helps an agent translate a request into the right include values. It does not expand on the auction-vs-issue distinction, which the schema handles well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List Treasury securities as at a date') and then enumerates the three distinct result modes: on-the-run per tenor, full outstanding universe, or priced CUSIPs only. The parenthetical about resolving 'the current 10-year' to a CUSIP makes it unmistakably distinct from the singular get_treasury_security and from price_treasury_security.

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 clear usage context, notably the concrete task of resolving a tenor reference to a CUSIP, and tells the agent how to handle the omitted-date case. It stops short of naming siblings as alternatives (e.g., use get_treasury_security for a single CUSIP), so there are no explicit exclusions to complete the routing picture.

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

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

The annotations already declare readOnlyHint, idempotentHint, and destructiveHint false, so the safety profile is known. The description adds useful behavioral context beyond that: the exactly-one-input constraint and the returned accrued interest, dirty price, and investment rate where applicable.

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 dense sentences, front-loaded with the core conversion behavior and followed by the input constraint and the CUSIP shortcut. No sentence is redundant.

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 nine-parameter pricing tool with no output schema, the description explains the output components and the central input rule, which is enough for an agent to call it correctly. It could be more explicit about which parameter sets are required for bills versus coupon securities, but the schema covers much of that.

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?

With 100% schema description coverage, the baseline is 3, but the description adds a meaningful cross-parameter constraint not encoded in the schema: supply exactly one of price or yield. It also clarifies that a bill uses a discount rate while a note or bond can use a CUSIP lookup.

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-plus-resource: converting between price and yield for Treasury bills, notes, and bonds. It clearly distinguishes the security types and the two directions of calculation, though it does not explicitly name sibling tools such as get_treasury_security or get_treasury_curve.

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 usage context: supply exactly one side, either a price or a yield, with a discount rate for a bill, and use a CUSIP for a note or bond to avoid restating terms. It does not name alternative tools or explain when a caller should use get_treasury_security instead.

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

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered without help from the text. The description contributes useful behavioral context by disclosing the HMDA provenance of the data. It does not mention data recency/lag, which matters for HMDA-sourced figures.

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 well-formed sentence with the resource and identifier first and the metrics and data source following. Every clause carries information, though the metric list is dense and slightly long for one sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With only two parameters, no output schema, and full annotation coverage, the description needs to convey what comes back, and it does by enumerating the metric categories. Only the staleness of HMDA data and the effect of the geography filter are left unspecified, which are minor gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so both parameters are already documented in the schema, making 3 the baseline. The description restates the name/NMLS ID input but never explains that the optional geography parameter narrows metrics to a state; the phrase "geographic footprint" refers to a returned metric, not the input, so it adds no meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb and resource ("Look up any US mortgage lender") and enumerates the returned metrics: origination volume, approval and pull-through rates, product mix, and geographic footprint. It also states the data source (federal HMDA). It stops short of explicitly distinguishing itself from the sibling find_lenders_in_market, which is a market-discovery tool rather than a single-lender lookup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description tells the agent which identifier forms are accepted (lender name or NMLS ID), which implies usage context, but it never says when to prefer this over find_lenders_in_market or get_market_context, and gives no exclusions or prerequisites. Usage guidance is implied rather than 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 safety profile (readOnly, idempotent, non-destructive, closed-world), so the bar is lower, and the description still adds value: it discloses that the return value is document ids for pages, and that results are static published references rather than computed per-borrower output. It does not mention how to resolve those ids (the fetch sibling) or any result-ordering behavior.

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 what is searchable, then the return type, then the scope caveat. Nearly every clause earns its place; the closing clause slightly restates the "published pages" idea already implied earlier.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description correctly carries the burden of stating that results are document ids. For a simple two-parameter read tool this is close to complete; the only meaningful omission is guidance on what to do with a returned document id, which matters given the fetch sibling.

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 documented with examples, so the baseline is 3. The description adds meaning beyond the schema by enumerating the entity classes a query can address (geography, lender, market rankings with optional loan/institution type), which helps an agent know what query strings are answerable.

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 verb (Search) and enumerates the exact resource classes covered: local mortgage-rate indexes by geography, lender profiles, lender rankings by market, and ranking methodology. It also draws a sharp boundary ("published reference pages, not priced scenarios"), which separates it from pricing-oriented siblings such as get_quote_estimate and from research_lender / find_lenders_in_market.

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?

Clear context is given for when this tool applies (finding published reference pages) and an explicit exclusion (it does not estimate a rate for a specific borrower). It stops short of naming the sibling to use instead for priced scenarios or for direct lender lookup, so the routing is implied rather than 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?

Beyond the annotations, the description discloses the required auth scope and confirms idempotent behavior: if an application already exists, nothing changes and it is returned. It also adds a meaningful privacy guarantee that no name, SSN, or date of birth is held.

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 compact and front-loaded: auth requirement first, then the action, then idempotency and privacy. Every sentence adds useful context without redundant wording.

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 complex 17-parameter write tool with no output schema, the description covers authentication, idempotency, and privacy well but omits parameter guidance and return-value shape. It is adequate on behavior but incomplete for correct invocation of such a parameter-rich 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?

The description does not explain any of the 17 parameters, and schema description coverage is 0%. It only refers generally to a 'loan scenario,' leaving required fields, enums, nested objects, and validation semantics to the schema without added 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 uses a specific verb and resource: 'Start building the shopper's Universal Application from a loan scenario.' It also clarifies the initialization behavior when an application already exists, which distinguishes it from retrieval or update tools.

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 states the prerequisite Safe Rate sign-in with scope poppy:write and explains that the tool is used to start an application from a loan scenario. It also clarifies that an existing application is returned unchanged, but it does not explicitly name alternatives such as get_my_application or update_my_application.

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, and closed-world semantics, so the bar is lower. The description still adds real value by enumerating the three returned data points (original scenario, rate drift, current rates) and explicitly stating no account or contact information is needed, which tells the agent no authentication context must be gathered.

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 short sentences, front-loaded with the action and followed by return contents and the no-credentials note. Every sentence carries information an agent would otherwise have to infer.

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 helpfully outlines the return payload, and it covers the single input's origin plus credential requirements. It is silent on failure modes such as an expired or unrecognized estimate ID, which is the only material gap for a one-parameter lookup.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% and the single estimate_id parameter is fully documented in the schema, including its provenance from get_quote_estimate. The description says "by its estimate ID" but contributes no format, validation, or lifecycle details 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 verb and resource ("Check a previously created Safe Rate rate estimate by its estimate ID") and states exactly what comes back: the original scenario, rate movement since creation, and current rates. The phrase "previously created" implicitly separates it from get_quote_estimate, which produces the ID in the first place.

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 clearly frames the use case as a follow-up on an estimate that already exists, and the schema's parameter note ("previously returned by get_quote_estimate") pins the prerequisite. There is no explicit anti-pattern or named alternative, so it stops short of a full when/when-not pair.

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=false, destructiveHint=true, idempotentHint=true, and openWorldHint=false, so the safety profile is covered. The description adds genuinely non-redundant behavior: the required auth scope, merge-not-replace semantics ('everything else keeps its saved value'), and all-or-nothing validation ('nothing is saved if the result would be invalid'). It does not describe rate limits or what the response contains after a successful write, but nothing contradicts 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?

Four short sentences, front-loaded with the prerequisite (sign-in scope) before the action, then the patch convention, then the hard limits. Every sentence adds information not available in the schema or annotations, and the em-dash clause on SSN/sharing is compact rather than padded.

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 an 18-parameter, nested-object, destructive mutation with no output schema, the description covers the critical unknowns: auth requirement, merge semantics, atomic failure on invalid results, and the conflict-relevant state assumption. Gaps remain around return value after a successful write and per-field meaning for the enums, but the fundamental call-shape risks are addressed.

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 only 6% (18 parameters, with only expected_updated_at documented in the schema), so the description carries most of the burden. It compensates partially by establishing that the call is a partial update in which omitted fields retain saved values, which is real meaning beyond the schema. However, it explains none of the domain parameters (creditBand, usdaArea, costOverridesMonthly, propertyAddressParts) or how the two address fields interact, leaving the bulk of the semantics undocumented.

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 verb ('Change answers') and a specific resource and sub-scope ('the loan scenario of the shopper's Universal Application'), which an agent can distinguish from get_my_application or start_my_application in the sibling list. It stops short of explicitly naming those siblings or stating the read-vs-write boundary, so differentiation is inferable rather than stated.

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 operating context (Safe Rate sign-in with scope poppy:write) and an explicit exclusion: sharing the application and recording an SSN cannot be done here and must happen on saferate.com. It also states the patch convention ('send only the fields that change'), which governs how to call it. It does not say when to prefer this over start_my_application (e.g., first-time creation), leaving one routing gap.

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

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

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false, so the safety profile is covered. The description adds genuine domain behavior beyond that: the penalty schedule that makes the received amount differ from accrued value, and the sub-twelve-month ineligibility. It does not describe the response shape or which rates/rate tables feed the calculation, which keeps it from 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?

Three sentences, front-loaded with purpose, then the two edge-case rules that most affect interpretation. Nothing is padding, and the high-stakes issue-date warning is placed where it will be read.

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 four-parameter read-only valuation with no output schema, the description covers purpose, key eligibility edge cases, and the composition of the result. The remaining gap is whether valuation uses live/current rate data or a static embedded schedule, which matters given the rated siblings in this server.

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 every parameter already carries a description, including the enum meaning and the issue-date pitfall. The description only reinforces the 'purchase date is the issue date' warning already present in the schema, adding no new syntax or default behavior. Baseline 3 applies 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?

The description opens with a specific verb and resource ('Value a U.S. Series I or Series EE savings bond') and even enumerates the three outputs: current worth, derivation, and net redemption amount. This clearly separates it from get_savings_bond_rates, which by name only supplies rates. It stops short of naming a sibling explicitly, so it lands at 4 rather than 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 redemption rules (three-month interest forfeiture under five years, no redemption under twelve months) implicitly tell the agent when this tool gives a different answer than a naive rate lookup. However, there is no explicit guidance on when to choose this over get_savings_bond_rates or how to handle unsupported series such as Series HH. Usage is implied rather than stated.

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