RateZip Bank Deposit and Mortgage Rates

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

Annotations declare readOnlyHint=true and destructiveHint=false, so the safety profile is already known. The description adds valuable behavioral context by stating it's 'Illustrative', declaring that it 'States every omission' (taxes, penalties, rate changes, tiers, availability), and adding 'Not financial advice'. This goes beyond the annotations and sets expectations about limitations.

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 three sentences and front-loaded with the main purpose in the first sentence. Every sentence earns its place: the second provides defaults, the third adds transparency about limitations and disclaimers. No wasted words.

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 simple calculator with good schema coverage, the description is nearly complete. It covers the calculation, defaults, and key caveats. However, it does not specify the output format (e.g., whether result is a number, currency amount, or percent), and there is no output schema to compensate. Still, the core context is well handled.

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 parameters are fully documented in the schema itself. The description adds little beyond what the schema already says—it mentions defaults that are also in the schema ('current = FDIC national average...' match the parameter descriptions). No additional meaning is provided, so the baseline score of 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?

The description clearly states a specific verb+resource: 'annualized earnings difference between two savings APYs for a given balance and horizon.' This distinguishes it from sibling rate lookups (get_cd_rates, get_mortgage_rates, get_savings_rates), which simply return rates rather than calculating a difference.

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 implies usage by stating defaults and scope ('for a given balance and horizon'), but it does not explicitly compare itself to alternatives or provide when/when-not guidance. There's no mention of 'use get_savings_rates if you only need current rates'. Usage is implied rather than explicitly directed.

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 indicate read-only and non-destructive behavior. The description adds valuable context about data sources (FDIC vs RateZip), the presence of observation timestamps, and staleness status, which goes beyond what annotations provide and gives a fuller picture of what to expect.

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 long, front-loaded with the core purpose, and efficiently packs essential details about data sources and filtering. Every sentence earns its place with no redundancy or filler.

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

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

With full schema coverage, read-only annotations, and a description that explains the data components and filtering behavior, the tool is sufficiently complete for an agent to understand what it does and how to invoke it. The absence of an output schema is compensated by the description's overview of returned data attributes.

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 input schema already has 100% coverage with descriptions for all parameters. The description adds concrete examples for term_months (3, 6, 12, 24, 36, 60) and clarifies the filtering behavior, providing extra semantic value 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 clearly states that the tool provides current CD APYs from FDIC national averages and RateZip-observed institution rates, including terms, minimums/conditions, timestamps, sources, and staleness. This distinguishes it from sibling tools like mortgage or savings rate getters, making the purpose unambiguous.

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

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

The description gives explicit guidance on using term_months to filter and that omitting it returns all terms grouped by term. However, it does not explicitly mention when not to use this tool or point to alternatives, lacking the full 'when/when-not/alternatives' specificity required for a 5.

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 description adds substantial behavioral context beyond the annotations: it discloses the data source (lenders' published rate pages), the fields included (note rate, APR, conditions, timestamp, source, staleness), and explicitly states that no third-party benchmark is redistributed and that data is factual, not a quote or advice. This aligns with readOnlyHint and avoids any contradiction.

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 yet information-dense, with four sentences each adding essential value: data source, grouping, filtering, caveats, and factual nature. No fluff or redundancy. The structure front-loads the main purpose and then details edge cases.

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 data retrieval tool with no output schema, the description is remarkably complete: it explains what data is returned, the grouping, the source, the filtering options, and important caveats (comparability, no fabricated rates, not advice). It gives an agent everything needed to invoke correctly 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 input schema already covers all four parameters with descriptive text (e.g., loan_amount flags conforming vs jumbo, credit_score returns educational context). The description only adds a brief note about filtering by loan_type and the comparison rule, which is more usage guidance than parameter semantics. With 100% schema coverage, 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?

The description clearly identifies the tool as retrieving current US mortgage rates grouped by loan type, with a specific verb ('get') and resource ('mortgage rates'). It distinguishes itself from sibling tools (CD/savings rates) by name and by explicitly stating the data scope and loan types.

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 provides clear usage context: it explains how to filter by loan type and notes that rates should only be compared within the same loan type. It does not explicitly name alternatives or state when not to use this tool, but the sibling tools are obviously different (CD/savings rates), and the instruction to 'omit for all' gives practical 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 flag read-only, and the description goes further by disclosing data provenance (RateZip observed pages), staleness status, and per-row timestamps. It also promises transparency in personalization and explicitly states nothing is fabricated, covering potential trust concerns.

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 purpose, and no filler. Each clause adds a distinct piece of 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 no output schema, the description usefully notes row contents (timestamp, source, staleness) and personalization behavior. It doesn't explicitly state the return shape (e.g., a list of institutions), but the 'every row' wording implies tabular results and is likely sufficient.

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 parameters are fully documented in structured fields. The description's 'balance resolves the applicable tier APY' echoes the balance schema and adds no new semantics; credit_score's 'clarifying note only' is also already in 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?

Description opens with 'Current savings APYs,' naming the exact resource and scope. It also distinguishes this from sibling rate tools by specifying savings accounts and citing FDIC national average plus RateZip observations.

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 implies this is for current savings rates but never explicitly states when to choose it over get_cd_rates or get_mortgage_rates. It offers no exclusion criteria or alternative recommendations.

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