RateSonar MCP

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

Annotations already cover readOnly/idempotent/non-destructive/not-open-world, but the description adds genuinely new traits: it returns cited claims, inference labels and dated records, marks partial readings with withheld sections, preserves records on AI failure, and rejects supplied rates. This is useful behavioral context beyond the structured fields.

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?

It is a single dense sentence chained with semicolons; reasonably compact with no filler, but the information is not front-loaded into scannable clauses, mixing purpose, scope and output behavior into one run-on.

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 describes the return shape (cited claims, inference labels, dated records, partial readings), which offsets some complexity from 8 parameters. However, it leaves the full parameter set and the required call preconditions unexplained, so it is only partially complete.

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

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

Schema description coverage is only 25% across 8 parameters, so the description is expected to compensate — but it explains none of amount, payment, loanKind, depositKind, loanKey, depositKey or question. Its only parameter-adjacent statement, 'No supplied rates accepted', is a constraint with no corresponding input 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?

The description names a specific resource ('an evidence-checked AI reading of bank_position') and enumerates its scope (savings/term deposits vs home, card, personal, car, business loans), which lets an agent distinguish it from the raw bank_position tool. The verb is implied rather than stated ('reading' rather than 'analyzes'), but the intent is legible.

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 explicit when-to-use guidance: nothing says to call this after bank_position or find_products, nor when to prefer it over siblings like compare_rates or rate_details. The prerequisite (institutionId from find_products) lives in the schema, not the description, so usage must be inferred.

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=true, idempotentHint=true, destructiveHint=false, openWorldHint=false), so the bar is lower. The description adds real value by naming the data sources consulted and explicitly bounding scope with "No claims about private ALM, intent or margins" – a useful limitation the annotations do not convey, though no output shape or granularity is described.

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?

Very short and front-loaded, with no padding. However, the opening sentence is a subject-less fragment that is harder to parse than it needs to be, which costs clarity relative to its brevity.

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 analysis tool with 8 parameters, 25% schema coverage, and no output schema, the description is thin – it neither explains what position data is returned nor how the cohort/loan/deposit parameters interact. The scope disclaimer helps, but an agent is left guessing at the tool's actual output and correct invocation.

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

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

Schema description coverage is only 25% (institutionId and depositKey), and 8 parameters exist, so the description must compensate. It names institutionId and gestures at a "product cohort," but leaves amount, payment, loanKey, loanKind, depositKind, and question entirely unexplained beyond their enums, so much of the surface is undocumented in both places.

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 fragment "Selected bank deposit and loan contracts against matching peer brands, own recorded history, RBA cash and dated funding disclosures" hints at a benchmarking/positioning operation but never states a clear verb+resource (list? compare? compute?). An agent cannot readily distinguish it from siblings like bank_analysis or compare_rates 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?

The description only says "Pass an institutionId and product cohort," which is parameter guidance, not when-to-use guidance. There is no mention of when to pick this over bank_analysis, compare_rates, or rate_details, and no prerequisites or exclusions 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 declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered by structured data. The description adds genuinely useful behaviour beyond that: per-product freshness via observedDate, the limit default/max, and the `truncated` flag signalling more rows exist. It does not add much else (no auth, rate limits or ranking-algorithm detail), so a 3 is appropriate against a strong annotation set.

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

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

Front-loaded with the core purpose and category list, then scoping rules, then return behaviour, with no filler sentences. Dense but each clause carries distinct, decision-relevant 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 carries the return-value burden and does so: best `limit` rows (default 25, max 40), a `truncated` indicator, and how fees are summarised versus the full detail in rate_details. Nothing an agent needs to call this 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?

Schema coverage is 100%, so the baseline is 3, but the description adds real semantic value: it defines what the headline home-loan rate means (owner-occupied P&I with LVR band covering 80%), how termMonths ranks published rates, and how customerSegment applies. This goes beyond the one-line schema descriptions.

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+resource ('Current comparison across institutions for a product category') and enumerates the categories, so an agent knows exactly what is returned. It also distinguishes itself from the sibling find_products ('It has no lender filter: for one lender's products use find_products').

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?

Explicit routing rule to find_products when a single lender is wanted, plus per-category applicability for termMonths, customerSegment and loan filters. It states 'Standard products only unless audience says otherwise', giving clear default behaviour and the condition to override it.

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 genuinely useful non-annotation context: the interpretation rule that an unhealthy status indicates a pipeline defect, not underlying bank risk. It stops short of describing the response shape or any latency/rate considerations.

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, no waste, and the content is front-loaded: what the tool reports first, then the interpretive caveat. Nothing is padded or restated from the title.

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

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

There is no output schema, so the description carries the burden of conveying return content, and it does list the concrete facets returned (validation, freshness, missing families, source hashes, fallback status). It does not describe the shape or format of those fields, which is a minor remaining gap for a zero-parameter diagnostic 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 tool takes no parameters, so there is nothing to disambiguate; the baseline for a zero-parameter tool is 4. The description correctly implies a parameterless, global status check rather than anything scoped.

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

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

Names a specific resource (the automated curve pipeline) and states exactly what the status covers: validation, freshness, missing families, source hashes and last-good fallback. This is clearly distinguishable from the analytical siblings (yield_curve, rate_history, bank_analysis), which operate on curve data rather than pipeline health.

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 second sentence implicitly frames the usage case: when a response looks unhealthy, treat it as a pipeline problem rather than bank risk. However, it never explicitly says when to call this tool versus the analytical siblings, nor does it state prerequisites or a recommended call order. Usage is inferable but not 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, non-destructive and non-open-world, so the safety profile is covered. The description adds real behavioral context: results are limited to *current* products, and each match carries category, rate and observed_date. It does not discuss pagination or matching/fuzzy-search behavior, keeping 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?

Three tight sentences, front-loaded with the verb+resource and an example, followed by return fields and routing. No sentence 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 compensates by naming the returned fields (institution_id, product_id, category, rate, observed_date) and the key identity semantics of a product pair, while annotations carry the safety profile. An agent has everything needed to call and chain it.

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

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

Schema description coverage is 100%, so the parameters (limit, query, category, institution) are already fully documented, and the description's examples for institution and query duplicate the schema's. It adds little input-side meaning 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?

States a specific verb and resource with scope: 'Find current products by lender and words in the product name,' plus a concrete example ('CBA' / 'standard variable'). It also defines what a product is, which disambiguates it from the sibling tools that operate on series and 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?

Explicitly routes to an alternative ('Use compare_rates instead to rank lenders for a category') and tells the agent what to do with the result ('pass both to rate_history or rate_details'). The condition that selects this tool versus its siblings is stated rather than inferred.

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, openWorldHint=false, so the safety/behavior profile is fully covered by structured data. The description usefully adds that this is a discovery-style prerequisite to `series` and enumerates the returned attributes, though it says nothing about result size or ordering.

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 short sentences, zero filler, and the payload description is front-loaded ahead of the routing instruction. 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?

There is no output schema, so the description must carry the return-value burden, and it does name the three returned attributes including the kind and unit enumerations. It stops short of describing the response shape or ordering, a minor gap for a static zero-parameter list.

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 4 baseline applies. The description mentions no inputs, which is correct here; its field list (label, kind, unit) describes outputs rather than parameters, so it neither adds nor detracts from parameter semantics.

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?

Specific verb-plus-resource: it enumerates every standard series slug accepted by the sibling `series` tool, and names the payload fields (label, kind level/spread, unit %/bps). An agent can distinguish it from `series`, `rate_details`, and `rate_history` without opening any 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?

States the exact condition for calling it ('when you do not know the slug') and names the alternative (`series`) as the follow-up. The inverse case (slug already known → skip straight to `series`) is directly implied by the conditional phrasing.

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 safety is covered. The description still adds genuinely new behavior: newest-first ordering, a default of 50 with a hard cap of 200, and a `truncated` flag for additional matches, plus the delta value format — more than the annotations provide, though it doesn't say how 'newest' is bounded beyond the schema's sinceDays default.

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 what an event is and what it contains before the filtering and paging details. No filler or repetition; 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 no output schema, the description carries the burden and does well: it enumerates the event fields (lender, product name/category, field-level deltas) and the truncation signal. Minor gaps remain — it doesn't note an event timestamp or identifier, nor state the look-back default — but nothing that would cause a wrong call.

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

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

Schema description coverage is 100%, so the schema already documents every parameter, and the description largely restates them (filters by institutionId, category, kind, direction; limit default 50, max 200). The delta example adds output understanding rather than parameter meaning, and sinceDays is omitted from the description's filter list.

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: it returns recent change-events (rate moved, product added, product withdrawn), newest first. The framing as 'a diff of RateSonar's consecutive captured observations' clearly separates it from sibling tools like rate_history and rate_details, which deal with series rather than change events.

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 context for when this is the right tool: you want recent deltas rather than stored history or a static product view, and it enumerates the available filters. It never explicitly names an alternative ('use rate_history for...') or an exclusion, so it stops short of a true 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?

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint=false, so the safety profile is covered. The description adds genuine context beyond that: data coverage begins 2026-06-12 and asOf resolves to the version current on a given date, which materially affects how the agent should call it.

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 core verb and scope, then the snapshot rule and the coverage caveat. The middle enumeration of returned fields is a long run-on that could be tightened, but it carries information and no sentence 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 usefully enumerates what is returned (rates, tiers, fees, features, eligibility, constraints, source quality flags, dates, lender links) and flags the 2026-06-12 data start. It omits edge behavior such as an asOf before the coverage start or a not-found product, which is a minor gap for a read-only 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%, so both required ids and asOf are already documented in the schema. The description's gloss on asOf ('returns the version current on that date') largely restates the schema's 'Latest snapshot on or before YYYY-MM-DD' and adds little parameter-level meaning, 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 states a specific verb+resource: retrieving exact CDR product-reference detail (every rate entry and tier) for one institution and product. It clearly distinguishes a single-product detail lookup from aggregate/temporal siblings, though it never names a sibling like rate_history or compare_rates 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 implied by the required institutionId/productId focus and the asOf snapshot semantics, but there is no explicit when-to-use/when-not-to-use guidance and no routing to alternatives such as rate_history or rate_changes. An agent must infer the boundary from the sibling names alone.

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 cover the safety profile (readOnly, idempotent, non-destructive), and the description goes well beyond them: record start date, carried-forward vs observed semantics, the 'never the next one' rule, the 14-day post-last-record cap tied to the gap ledger, and the gridError fallback. This is unusually rich behavioral 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?

Front-loaded with the core purpose before the grid mechanics, and every sentence carries semantic weight rather than filler. It is dense and long, but the density is earned by the carried-forward rules that cannot be inferred elsewhere.

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 returns, and it does: each recorded rate, comparison rate, fees, and recording date, plus the grid shape. Combined with the parameter sourcing hints, 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?

Schema coverage is 100%, so the schema already documents all five parameters and the baseline is 3. The description adds genuine meaning beyond the schema by explaining what a grid point actually is (observed vs carried-forward, sourceDate, fill reason) and stressing that institutionId+productId form a pair, pushing it 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 and resource with scope: 'Advertised rate history for one product (institutionId and productId)' between two dates. It is clear what the tool returns, but it never names or contrasts with the closest siblings (rate_changes, rate_details, series), leaving the agent to infer the boundary.

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 some usage context: productId comes from find_products or compare_rates, and grid:true triggers the daily grid with a 367-day cap. However, there is no explicit guidance on when to choose this tool over rate_changes or rate_details, so the selection condition is only implied.

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 only declare the safe-read profile (readOnly, idempotent, non-destructive), and the description adds substantial context beyond that: carried-forward status with sourceDate and fill{from,through,ageDays,reason}, the 14-day carry limit tied to the gap ledger, derived status for spreads/medians, and tier-based clamping. This is exactly the behavioral detail structured fields do not carry.

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 concept (LEVEL and SPREAD series per institution per day) is front-loaded, which is good, but it then collapses a large amount of carry-forward, gap-ledger, and tiering detail into a single dense paragraph. The information is valuable but the structure is a wall of text with no separation, making it harder to scan than it needs to 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?

For a complex domain tool with no output schema, the description covers return semantics well: carried-forward vs derived statuses, sourceDate/fill fields, gap behavior, and unauthenticated clamping. It is close to complete, though it never outlines the overall response shape or how institutions filter interacts with the returned points.

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 adds real meaning: it decodes slug syntax (hl.var.oo.pi = headline variable home loan, cash = RBA cash rate), explains the LEVEL vs SPREAD distinction and bps units, and clarifies the effect of median:true. This goes beyond the schema's terse field notes.

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?

It states a specific verb+resource: it returns named LEVEL series (hl.var.oo.pi, sav.max, cash...) and SPREAD series per institution per day, with concrete slug examples that make the domain unambiguous. It does not, however, differentiate itself from siblings such as rate_history or compare_rates, which the agent must infer.

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 operational when-to guidance (pass median:true for a market-median line; unauthenticated access is clamped to 31 days; full-archive tiers must use windows of at most 367 dates) and points to list_series for slugs. But it never states when to choose this tool over siblings like compare_rates or rate_changes, so the routing guidance is implied rather than explicit.

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 description earns credit for adding publishing cadence ('zero/forward fitted data publish monthly') and provenance details ('each point says whether it is observed or derived'). The freshness caveat is material for a data-retrieval tool and is not present in 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 purpose is front-loaded in the opening clause and the two follow-up sentences add genuine constraints rather than filler. The first sentence is a dense multi-clause list, but it remains readable and every element 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 no output schema, the description carries the burden of describing returned data, and it does so reasonably: yields, fitted curves, observed-vs-derived markers, source digest and convention. It stops short of describing the response shape or how multiple families interleave, but it is sufficient for correct invocation.

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

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

Schema coverage is 67%, and the schema already spells out date, compareDate and the family enum. The description only adds the count of families ('eight distinct cash/government families') without mapping individual enum values or explaining the family semantics, so it does not meaningfully compensate for the coverage gap. 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 resource (RBA curve nodes) and enumerates the returned content: cash and bond yields as published plus fitted zero, forward and discount curves with observed/derived flags. It does not name a specific sibling to contrast against, but the scope is unambiguous enough to separate it from rate_history or compare_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?

Gives explicit selection context ('exact date or the latest publication') and an explicit exclusion boundary ('no intraday OIS, BBSW, swap or futures feed'). It does not name alternative sibling tools for those excluded use cases, so the routing stops just short of a 5.

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