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

Annotations already declare a safe, idempotent, open-world read, so the bar is lower. The description still adds real behavioral substance: the 12-month-high threshold for welcome offers, the restriction to cards not held, and that the savings move is contingent/optional. It does not disclose cost, latency, or freshness of 'this week's' data, 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?

A single dense sentence that front-loads the input premise and then lists the ranked outputs in priority order. Nothing is wasted; the parenthetical for the optional savings move keeps the conditional out of the main clause.

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?

Because an output schema exists, return values needn't be explained, and the description covers the input premise and the dimensions being ranked. It is slightly thin on how 'this week' is bounded and on what happens when wallet cards have no offers, but nothing critical for 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 the schema already documents wallet format, category defaults, usedBenefits semantics, and savings fields, making 3 the baseline. The description adds only light framing — 'per spend category' for categories and '(optionally)... beside the card move' for the savings pair — which is marginal beyond the schema text.

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 ('rank'), a specific resource ('this week's dollar-valued actions'), and enumerates the four action classes it produces (held-card category picks, 12-month-high welcome offers on unheld cards, transfer bonuses, optional savings move). No sibling tool does this synthesis, so an agent can separate it from get_card_offers or get_transfer_bonuses 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 context is clear: it operates 'Given the credit cards a user holds,' which frames the required wallet input and implies a personalized, portfolio-wide aggregation rather than a single-dataset lookup. It stops short of explicit exclusions or naming alternatives (e.g. 'use get_card_offers if you only want offers'), so it is clear context without 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, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds that the comparison is against a live 'current' top APY for a given balance, but says nothing about rate freshness, data source, 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?

A single tight sentence with the comparison target and scoping input front-loaded. No waste, though it is perhaps over-compressed for a tool with two non-obvious parameters.

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?

An output schema exists, so return values need not be explained, and the read-only annotations cover safety. Still missing is any note on which rate source backs the 'top APY' and whether the optional balance changes the result, which the agent needs to invoke confidently in this sibling-heavy cluster.

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 0%, so the description must carry the burden: it names both parameters implicitly ('current APY', 'balance') and gives each meaning. However, it adds no units or format detail (e.g. APY as a percent number vs decimal, balance currency), which matters given the schema's max of 25 on currentApy.

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 (compare) and both resources (the user's current APY vs SwitchWize's top savings APY) scoped by balance. An agent can tell what it does, though it does not explicitly distinguish itself from rate-list siblings like get_top_hysa_rates or get_bank_gap.

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?

No when-to-use guidance, no prerequisites, and no mention of alternatives in a crowded sibling set (get_top_hysa_rates, get_bank_gap, best_move_this_week). Usage must be inferred entirely from the single purpose sentence.

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 and destructiveHint=false, so the safety profile is covered. The description adds genuinely non-structured context: comparisonApy is the average of the top three tracked rates rather than a market-wide average, bankCount bounds that set, and the result is explicitly a hypothetical estimate requiring the user to verify eligibility, fees and provider terms. That methodology disclosure is exactly the kind of value annotations cannot 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 purpose is front-loaded in the first clause, followed by methodology and then caveats — a sensible ordering. Four sentences is defensible, but the enumeration of return fields ('annualGap, APYs, observation date, freshness and methodology') duplicates the output schema and is the one sentence that does not earn its place.

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 an output schema present, describing return values was optional, and the annotations already carry the safety profile, so the description's remaining job is purpose, metric semantics and caveats — all present. The one real hole is routing: an agent cannot tell from this text when to prefer it over get_bank_gap_index or compare_switch_savings.

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 50% — the bank parameter is documented, balance is not. The description compensates by clarifying that bank is optional and, more importantly, that omitting it swaps baselineApy from the named bank's APY to the national savings benchmark, which is real semantic meaning the schema does not convey. It still says nothing about balance units, though the number type plus the 10,000,000 maximum makes dollars the obvious reading.

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: 'Estimate annual savings interest forgone for a supplied balance and optional bank name,' which tells the agent exactly what question the tool answers. It defines the headline metric (annual savings interest forgone) concretely enough to separate it from rate-listing siblings like get_top_hysa_rates. It does not, however, address the closely named sibling get_bank_gap_index, so full differentiation is left to inference.

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 never says when to reach for this tool rather than get_bank_gap_index, compare_switch_savings, or get_top_rates; only a caveat ('hypothetical estimate, not an account recommendation') is given. The 'optional bank name' phrasing implies a no-bank vs named-bank use case, but that is inference rather than stated guidance. No exclusions, prerequisites, or alternatives are named.

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, destructiveHint=false, idempotentHint=true, fully covering the safety profile for a zero-parameter lookup. The description adds only that the result is the headline value plus release and methodology URL, which is modest added context but nothing beyond the annotated read-only, idempotent nature.

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 front-loaded sentence that names the resource first and enumerates the returned fields without filler. Every clause earns its place.

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-parameter read with an output schema present, the description needs only to frame the resource, which it does. The one real gap is that it never clarifies its relationship to the near-identical sibling get_bank_gap, so an agent could still pick the wrong one.

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 convey; per the rubric this is the baseline of 4. Nothing in the schema needs compensating for in the description.

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 ('Return the current SwitchWize Bank Gap Index headline value, latest release, and methodology URL'), so the agent knows exactly what it produces. It does not, however, distinguish itself from the closely named sibling get_bank_gap, leaving ambiguity about which is the right tool for the gap index.

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 when-to-use guidance, no prerequisites, and no reference to alternatives such as get_bank_gap or get_index_dataset. The agent must infer the selection criteria purely from the name.

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, open world), so the description is not obligated to restate it. Instead it adds genuinely useful behavior: results are 'verified' and ordered 'most recent first', and each event is a diff between two confirmed snapshots, which tells the agent the data model and that entries represent changes rather than current values. It does not mention pagination or coverage limits, keeping it at 4.

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

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

Two dense sentences with no filler; the core purpose is front-loaded and the diff semantics are appended as a clarifying second sentence. 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?

An output schema exists, so return values need not be explained, and the description supplies the ordering and diff semantics that matter most for interpreting results. The only gap is the unexplained 'limit' parameter, which is minor given the output schema covers shape.

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 only 50%: 'sinceDays' is documented in the schema, but 'limit' has no description beyond its min/max bounds. The description mentions 'recent' but adds no meaning about how limit or sinceDays behave, so it fails to compensate for the uncovered parameter.

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 ('Return recent verified credit-card fee and APR changes'), which is clearly distinct from siblings like get_card_offers or get_rate_freshness. It further sharpens the purpose by defining each event as a diff between two confirmed snapshots, so an agent knows this is a change-feed rather than an offer or rate listing. It stops short of explicitly naming the sibling it displaces, so 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?

There is no explicit when-to-use, when-not-to-use, or alternative-tool guidance. 'Recent' hints at a recency use case, but the agent must infer when to pick this over get_card_offers, get_rate_freshness, or the rate/offer siblings. 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, so the safety profile is fully covered elsewhere. The description adds the useful qualifier 'verified' (curated data, not raw scrape) and clarifies that the refund window is tied to when the annual fee posts. It says nothing about freshness, pagination, or auth needs, so this is adequate but not rich.

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 return payload and followed by the optional filter. The parenthetical expansion of 'product-change' earns its place by disambiguating the term, and there is no 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 an output schema present, the return shape needn't be described, and the tool has only one optional parameter whose schema is complete. The definition covers what is returned, the default behavior when the filter is omitted, and the data's verified nature – nothing an agent needs 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?

Schema description coverage is 100% and the single cardId parameter is fully documented in the schema, including the issuer:slug format and examples. The description's mention of the same filter and the omit-to-return-all behavior largely restates the schema, 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 (Return) plus a precisely scoped resource: verified credit-card product-change (downgrade) paths and the issuer's fee-refund window. It even defines the concept inline ('which no-fee or lower-fee card a given card can be product-changed to'), so an agent knows exactly what it gets. It never names the adjacent siblings (get_card_changes, get_card_offers), so it stops short of explicit differentiation.

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

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

The second sentence gives filtering guidance ('Optionally filtered to one card id... returns every verified path and window when omitted'), which tells the agent how to scope the call. However, there is no tool-level when-to-use versus alternatives, and no indication of when get_card_changes would be the better choice.

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, openWorld, non-destructive), so the bar is lower; the description still adds real context by disclosing that results are confidence-gated, non-targeted, and carry a verified timestamp plus source URL. This tells the agent about data trustworthiness, which the annotations do not. It does not discuss pagination or staleness limits.

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 sentence that is front-loaded with the core action and packs scope, filtering behavior, and payload shape without a wasted clause. Nothing here 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 listing tool with an output schema, the description is nearly sufficient: return values need not be spelled out but are summarized anyway, and scope qualifiers are given. The remaining hole is the undocumented 'limit' parameter, which the description and schema both leave silent.

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 only 50%: the 'card' parameter is documented in the schema, but 'limit' has no description anywhere. The description mentions no parameters at all, so it fails to compensate for the coverage gap, particularly the missing semantics of the result cap and its interaction with the 200 maximum.

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+resource: returning current credit-card welcome-bonus offers, with scoping qualifiers (non-targeted, confidence-gated) and the per-card payload. An agent can distinguish this from siblings like get_transfer_bonuses or get_reward_valuations by resource. It stops short of naming any sibling, so sibling differentiation is inferred 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?

Usage is implied: fetch it when you need live welcome-bonus offers. The 'non-targeted' qualifier hints at a scope boundary (targeted offers presumably live elsewhere), but there is no explicit when-to-use or when-not-to-use guidance and no alternative tool is named.

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, open world). The description adds genuinely new behavioral context: data provenance from the bank's own disclosure and the rule that unverified fields are omitted rather than guessed, which tells the agent to expect partial objects and not to treat missing fields as errors.

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, tightly front-loaded: the first gives the operation and scope, the second gives the data-quality guarantee. No filler, no restatement of the tool name, and the most decision-relevant information (scope) comes first.

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?

An output schema exists, so return-value explanation is unnecessary. Within that constraint the description supplies everything an agent needs: what is returned, for which entity, the sourcing guarantee, and the omission semantics for unverified data.

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

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

Schema description coverage is 100% and the single institutionId parameter is fully documented in the schema, including the omit-for-all-banks behavior. The description restates that scope but adds no format, id-validation, or edge-case detail beyond the schema, 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?

States a specific verb and resource ('Return verified CD rollover rules') plus the exact scope: one bank or every verified bank. It also enumerates the returned facts (maturity behavior, grace period, stop-rollover method, early-withdrawal penalty), which cleanly separates it from the rate-, card-, and bonus-oriented 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?

The scope branch is explicit — pass an institution for one bank, omit it for all verified banks — which tells the agent how to invoke it in either case. It doesn't state when to prefer a sibling tool over this one, but the sibling set covers unrelated domains (rates, cards, bonuses), so ambiguity is low.

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 carry the safety profile (readOnlyHint=true, idempotentHint=true, openWorldHint=true, destructiveHint=false), lowering the bar. The description still adds real behavioral context beyond them: 'one source per bank,' per-row source type, and observation dates, which tell the agent how to interpret provenance and freshness of each row.

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

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

Two dense sentences: the first front-loads what is computed and the exact output fields, the second covers dataset structure and the optional filter. No filler, no repetition, and the most important information leads.

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, single-optional-param tool with an output schema and full annotation coverage, the description supplies what's needed: the computation being reported, row granularity, provenance, and the filter. The only marginal gap is that it doesn't touch freshness/staleness expectations, but get_rate_freshness exists as a sibling for that concern.

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

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

Schema description coverage is 100% and the single optional institutionId is fully documented in the schema (including example ids like tab, ally, marcus). The description merely restates that the filter is optional and scopes it to 'one institution id,' adding no format or behavior detail 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+resource (return Fed-hike pass-through per savings account) and enumerates the exact metrics returned: rate before, rate now, basis-point change, pass-through share, days to move. That framing cleanly separates it from siblings like get_top_hysa_rates or get_bank_gap, which measure levels and gaps rather than pass-through of a specific hike.

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 description notes the result can be 'optionally filtered to one institution id,' which hints at the unfiltered-aggregate vs single-bank modes. It never states when to reach for this instead of get_bank_gap, get_reality_score, or best_move_this_week, nor any precondition for calling 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 declare readOnlyHint, idempotentHint, openWorldHint, and destructiveHint, so the safety and idempotency profile is covered. The description adds that it returns a 'summary and recent series,' which hints at output shape but doesn't specify pagination, rate limits, or what 'recent' means. With annotations already conveying core behavior, this is adequate but not rich.

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's a single, efficient sentence with no fluff, though it could be slightly more front-loaded by leading with the action and result. 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?

An output schema exists, so return values needn't be explained. However, for a tool with siblings that serve similar purposes, the description lacks the routing information needed to pick this tool correctly. The parameter gap (undocumented 'limit') also leaves an incompleteness.

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

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

Schema coverage is 50%. The indexId parameter has a description with examples in the schema; the limit parameter has no description in the schema or in the description text. The description doesn't compensate for the missing limit documentation. Baseline 3 is appropriate when schema partially covers parameters.

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 verb and resource: 'Return a SwitchWize index dataset summary and recent series.' This is clear enough to understand the tool's output, but it doesn't distinguish it from siblings like get_bank_gap_index or get_bank_gap. An agent could confuse this generic 'index dataset' tool with those specific index 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?

No when-to-use guidance is provided. It doesn't mention alternatives, conditions, or exclusions. With many similar-sounding sibling tools, this omission is significant.

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, openWorld and non-destructive, so the safety profile is covered. The description adds only that the output includes freshness status and affected routes; it says nothing about staleness thresholds, caching, or why 'openWorld' applies 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?

A single front-loaded sentence with no filler; the primary output is named first and the secondary output follows.

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?

The output schema exists, so return values need not be explained, and annotations cover safety. Still, the lone unexplained parameter and the undefined term 'affected routes' leave meaningful gaps for an agent deciding whether and how to call this health-check 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 single optional 'category' parameter has 0% schema description coverage and no enum, and the description never references it. The 'public data source' phrasing only faintly hints that 'category' might scope the source type, leaving its meaning and valid values to inference.

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 ('Return ... data source freshness status') plus a second output ('affected routes'), which sets it apart from the rate-fetching siblings. However, 'freshness status' and 'affected routes' remain loosely defined, so an agent knows the domain but not exactly what a 'route' is.

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?

No when-to-use guidance and no mention of any alternative. With 15 sibling tools all fetching or comparing rates, the description never says this is the metadata/health check to consult before trusting those results, nor any precondition for calling 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 cover the safety profile (readOnly, idempotent, non-destructive, openWorld), but the description adds real behavioral context: it defines every derived ratio (breakageMultiplier, feeRecoveryMultiplier, friction, Reality Score), warns that these are scenario estimates, and instructs how to handle stale/unavailable labels. It also discloses that unknown cards/segments return a structured error with suggestions. This goes well beyond the annotations, though some overlap with the output 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?

The purpose and required inputs are front-loaded correctly, but the middle of the description is a dense run of formula definitions (breakageMultiplier, feeRecoveryMultiplier, friction, Reality Score) that partly restates what the output schema can carry. Several sentences do real work, but the block is longer than needed for a 2-parameter read tool.

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 estimation tool with a full output schema and complete annotations, the description covers the remaining gaps: default segment, error behavior, the meaning of every computed ratio, caveats about scenario estimates, and stale-label handling. An agent has everything it needs to call this correctly.

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

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

Schema description coverage is 100%, so the schema already documents both parameters (card and segment) with examples. The description adds only the default value for segment (occasional-traveler), which is not in the schema, and restates card-or-name input. 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 opening sentence gives a specific verb+resource+scope: "Estimate the modeled annual value of a supported premium credit card for a consumer segment." It clearly defines the Reality Score concept. However, it never distinguishes itself from the closest siblings (get_reward_valuations, get_card_offers, get_card_downgrade_path), so an agent must infer which card-value tool to pick.

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 invocation basics ("Supply a card slug or name and optionally a segment ID; the default is occasional-traveler") and notes error behavior for unknown inputs, but gives no when-to-use vs when-not guidance and names no alternative among the many sibling card tools. Usage is implied rather than 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 declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so safety behavior is covered. The description adds useful context beyond the schema by disclosing that results carry sample size and a provisional/published status, but it omits any behavioral notes about freshness, coverage, or defaults.

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 front-loaded sentence with no filler; the core action leads and the detail clauses follow. Slightly dense 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 an output schema present, return values need not be described, and annotations cover the safety profile. The description covers purpose, unit, and result metadata; the only gap is not stating what happens when 'currency' is omitted (all currencies), which is minor.

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 single optional 'currency' parameter is already fully documented. The phrase 'per reward currency' reinforces that results are currency-scoped, but adds no syntax or format detail beyond the schema, which is the expected 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?

The description uses a specific verb and resource ('Return SwitchWize points/miles valuations (cents per point) per reward currency') and even names the unit. It is clear what the tool retrieves, though it does not explicitly differentiate itself from siblings like get_transfer_bonuses or get_index_dataset, which an agent must infer from the domain.

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 when-to-use guidance, no statement of prerequisites, and no routing to alternative siblings. The agent must infer usage entirely from the tool name and description.

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 cover the safety profile (readOnly, idempotent, openWorld), yet the description discloses the non-obvious behavioral gate: results come solely from the editor-approved snapshot, and before first release it returns no ranked rates with approval_status: not_yet_approved. It also enumerates what detail=full unlocks. This is meaningful context an agent could not infer from 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?

Four front-loaded sentences with the core purpose first and the edge-case behavior second. The sentence 'approvedOnly makes the requirement explicit' is largely redundant with the preceding clause and the schema description, a minor waste.

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?

An output schema exists, so return-format detail is rightly omitted, and the description covers the important exception path (pre-approval empty result) plus detail modes and attribution. Only the undocumented limit parameter and the absence of sibling routing keep it from being fully 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 coverage is 67% (detail and approvedOnly are documented; limit is not), so the schema already carries most parameter meaning. The description largely restates the schema's detail/approvedOnly text, adding only minor framing, and leaves limit's 1-25 bounded meaning unexplained.

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 ('Return top high-yield savings rates') and adds scope qualifiers (freshness, attribution, editor-approved snapshot). It is clearly distinguishable from the generic sibling get_top_rates by the HYSA focus, though it never names that sibling 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?

No when-to-use or when-not-to-use guidance relative to the many siblings (get_top_rates, get_rate_freshness, get_bank_gap). The description explains parameter-driven behavior but never tells an agent which of the competing rate tools to pick in a given situation.

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 read-only, idempotent, non-destructive behavior, and the description adds real context on top: the editor-approval gate, the not_yet_approved fallback, and that stale/unavailable releases yield no ranked rates. What it does not clarify is the default page size, ordering, or what 'field evidence' concretely contains.

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?

Purpose is front-loaded and the sentences are information-dense, but the approvedOnly and detail=full sentences duplicate the schema's parameter descriptions almost verbatim, which is wasted space. The jargon ('shared build', 'field evidence', 'movers') also goes unexplained.

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 an output schema present, the description needn't explain return values, and it does cover the key conditional behaviors (approval gating, staleness, detail levels). The gaps are the absence of sibling routing and the unspecified default/ordering for limit.

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 75% and the schema already documents approvedOnly and detail in detail. The description largely paraphrases those same parameter texts (approval_status, detail=full contents) rather than adding new syntax or constraints, so it lands at the baseline for well-covered schemas.

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 first sentence states a specific verb and resource ('Return top SwitchWize rates') plus the freshness/attribution framing, which is far more than the title restates. It does not, however, distinguish itself from the very close sibling get_top_hysa_rates or get_rate_freshness, so an agent still has to guess which 'top rates' tool applies.

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 through category scoping ('savings, CDs, checking and money market answer only from their editor-approved snapshot'), but the description never says when to pick this over get_top_hysa_rates or the freshness/reality-score siblings. The reader must infer the boundary.

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 open-world, so the safety profile is covered. The description adds one genuinely useful behavioral trait: 'best-ever-for-route when real history exists,' disclosing that a field is conditionally populated. Everything else it mentions (timestamp, source URL) restates return values already covered by the output 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?

A single front-loaded sentence with no filler; the core action leads and the output details follow. Slightly dense and could be split, 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?

For a simple read-only tool with one optional parameter, a full schema, and an output schema, the description covers purpose and return provenance adequately. The only real gap is routing guidance against the many sibling tools in this rate/deal family.

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

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

Schema description coverage is 100%, and the single optional 'program' parameter is fully documented as filtering by source or destination with examples. The description adds nothing about filtering semantics, so 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 ('Return current point-transfer bonuses') and scopes it to 'tracked bank-to-partner routes,' which clearly separates it from rate, card-offer, and valuation siblings. It does not name a sibling, but the domain is 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?

There is no when-to-use or when-not-to-use guidance, no mention of alternatives (e.g. get_card_offers, best_move_this_week), and no prerequisites. The usage context is only implied by the resource name.

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