US bank, savings and credit-card signup bonuses, each source-checked, with expiry dates.
Scored across 6 tools
The six tools have largely distinct purposes: search_bonuses finds offers, get_bonus retrieves one offer's details, compare_bonuses compares selected offers, and expiring_soon filters by timing. Minor overlap exists because search_bonuses and expiring_soon both return offer lists, and get_bonus/compare_bonuses both retrieve offer fields, but the descriptions make the intended use cases clear.
Most action tools follow a verb_noun pattern (search_bonuses, get_bonus, compare_bonuses), but expiring_soon is adjective-based and the two meta tools use a benefits_ prefix. The names remain readable, but the set mixes conventions enough to be noticeable.
Six tools are well-scoped for a read-only bank bonus discovery server. Search, retrieval, comparison, expiry filtering, and documentation/examples each earn a place without redundant surface area.
The tool set covers the core lifecycle of discovering, inspecting, comparing, and timing bank signup bonuses. Minor gaps exist, such as no dedicated state/category filter or bulk export, but agents can work around these using search_bonuses and get_bonus.
Use when you need field definitions, ordering guarantees or the error format before calling another tool.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| docs | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds the doc's topical scope, which helps with the go/no-go decision, but says nothing about freshness, caching, size or whether the content is static — minor behavioral gaps for a docs endpoint.
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 trigger condition comes first and each clause (field definitions, ordering guarantees, error format) earns its place by scoping the content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With zero parameters, full schema coverage, an output schema covering the return payload, and annotations covering safety, the description supplies everything needed to decide to call it. Only a note on staleness or scope limits would add more.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. Schema coverage is 100% and the empty object schema is consistent with a no-argument docs read.
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 enumerates the concrete content the tool exposes ('field definitions, ordering guarantees or the error format'), which clarifies the resource well enough to separate it from siblings like benefits_examples, search_bonuses and get_bonus. It stops short of an explicit verb ('returns/reads the server docs') and leans on the title for the resource framing, so it is clear but not fully self-contained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives a clear trigger — use it 'before calling another tool' when you need field definitions, ordering rules or error format. That is actionable context, but it names no alternatives or exclusions (e.g. when the examples or search tools are preferred instead).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use to copy a working example call instead of guessing tool arguments.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| examples | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false and openWorldHint=true, so the safety profile is covered. The description adds nothing beyond that: it does not say whether the examples are scoped to a tool, returned as a list, or whether the output is static or live. With annotations carrying the safety burden, the marginal behavioral content is near zero.
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 short sentence, front-loaded with the subject. It wastes no words, though the phrasing 'Use to copy...' is slightly informal and the sentence could have carried more routing information at no length cost.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no parameters, an output schema present, and annotations covering safety, the structured data carries most of the load, so the description is close to sufficient. What it still leaves open is the key routing question among five siblings: when an agent should call this instead of benefits_api_docs. That gap keeps it at minimum viable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so per the rubric the baseline is 4 and there is nothing for the description to compensate for. The description's implicit warning against guessing arguments does not need to document parameters that do not exist.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The name and title both signal a retrieval of runnable examples, and the description states the intent (copy a working example call). But the verb is soft ('use to') and the description never says what is being fetched or from where, nor does it distinguish itself from the sibling benefits_api_docs, which an agent might reasonably pick instead.
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 implies a situation (when you don't want to guess arguments), which is a mild use cue, but it gives no when-not guidance and never references benefits_api_docs, the obvious alternative sibling. The agent gets no rule for choosing between this and the docs tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when a user is choosing between specific offers. Returns each offer's key fields plus a summary naming the highest bonus and the earliest expiry.
| Name | Required | Description | Default |
|---|---|---|---|
| ids | Yes | 2 to 4 bonus ids to compare, e.g. ['chase-total-checking-400', 'sofi-checking-savings-400']. |
| Name | Required | Description |
|---|---|---|
| bonuses | Yes | |
| summary | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description's return-value detail (summary of highest bonus and earliest expiry) overlaps with the existing output schema and adds no auth, rate-limit, or mutation-consequence context.
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 tight sentences with no waste, usage guidance front-loaded. The second sentence largely restates the output schema's contents, which slightly dilutes the value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool with full annotations and an output schema, the description covers the triggering scenario and what the comparison returns. Little 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 parameter is fully documented with format and examples in the schema. The description adds only the vague phrase "specific offers," so the 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 states what the tool produces: each offer's key fields plus a summary naming the highest bonus and the earliest expiry. This makes the comparison function clear, though the action verb itself is only implied rather than stated outright.
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?
"Use when a user is choosing between specific offers" gives a clear trigger condition, so an agent knows when this applies. However, it names no alternatives (e.g., get_bonus, search_bonuses) and gives no when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when timing matters — a user asking what is about to end, or whether to act now. Offers with no stated end date are never included here.
| Name | Required | Description | Default |
|---|---|---|---|
| days | No | Lookahead window in days (default 30). |
| Name | Required | Description |
|---|---|---|
| bonuses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only profile (readOnlyHint, destructiveHint=false, openWorldHint), so the bar is lower. The description still adds a genuine behavioral rule absent from structured data: offers with no stated end date are never returned. It omits ordering, pagination, and the default window, keeping it from a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, front-loading the trigger condition before the scope caveat. 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?
Return values are covered by the output schema, safety by annotations, and the parameter by the schema, so the description only needs to add selection guidance and edge behavior — both present. It could be more explicit about the days window and sibling routing, but nothing essential 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?
The schema documents the single parameter (days, default 30, range 1-365) at 100% coverage, so the baseline is 3. The description adds nothing about the lookahead window or how days interacts with the results, leaving the schema to carry full param 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?
The title ("List bonuses expiring soon") plus the description make the resource and scope clear: it surfaces offers that are about to end. The description itself never restates the verb/resource ("lists bonuses within a lookahead window"), and it does not distinguish this from siblings like search_bonuses or compare_bonuses, so it lands just below the top.
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?
"Use when timing matters — a user asking what is about to end, or whether to act now" is an explicit, actionable when-to-use cue tied to user intent. It names no alternatives or when-not conditions, so an agent gets context but no routing exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use before recommending an offer, to read its exact requirements, minimum deposit, direct-deposit rules, expiry date, state availability and the date its terms were last verified. Quote the requirements rather than paraphrasing money amounts.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | Bonus id, e.g. 'chase-total-checking-400'. Use search_bonuses to find ids. |
| Name | Required | Description |
|---|---|---|
| bonus | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish the safe read-only, non-destructive, open-world profile. The description adds genuinely new operational context: that a "terms last verified" field exists (data recency) and that money amounts should be quoted verbatim rather than paraphrased. It does not cover behavior on a missing/invalid id.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste, with the usage trigger front-loaded ahead of the field list. The dense enumeration of returned fields is information-bearing rather than filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need no explanation, and annotations carry the safety profile. The description covers when to call it and what it yields; only error/not-found behavior for an invalid id is unaddressed, a minor gap given the otherwise complete coverage.
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 id parameter is already documented with a concrete example plus a pointer to search_bonuses for discovery. The description adds nothing further about the parameter, 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 makes clear this tool reads the full detail of a single offer, enumerating the exact fields returned (requirements, minimum deposit, direct-deposit rules, expiry, state availability, verification date). It distinguishes itself implicitly from search_bonuses via the id lookup, but never names the sibling it is not, 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?
"Use before recommending an offer" gives a concrete workflow trigger, which is strong guidance for an agent. It stops short of naming alternatives (e.g. search_bonuses for discovery, compare_bonuses for side-by-side) or stating exclusions, so it falls just below the explicit when/when-not bar.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Use when a user wants to find a US bank account, savings, or credit card signup bonus, or asks which offers are worth opening. Returns matching offers sorted by bonus value, highest first.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max results to return. | |
| query | No | Keyword matched against bank/issuer and product name, e.g. 'Chase' or 'Sapphire'. | |
| state | No | 2-letter US state code, e.g. 'TX'. Nationwide offers always match; regional offers match only their states. | |
| bonus_type | No | Restrict to bank account bonuses, credit card signup bonuses, or savings account bonuses. | |
| min_bonus_amount_usd | No | Minimum bonus value in USD. For credit cards this is the estimated USD value of the points/miles bonus. | |
| direct_deposit_required | No | Filter on whether the bonus requires a qualifying direct deposit. |
| Name | Required | Description |
|---|---|---|
| bonuses | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false, openWorldHint=true), so the bar is lower. The description does add two useful behaviors beyond structured data: US-only scope and the fact that results arrive sorted by bonus value descending. It says nothing about pagination behavior or how the limit interacts with total matches.
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: the trigger condition is front-loaded and the return behavior follows. Every clause earns its place with no restatement of the name or schema.
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, an output schema, and annotations present, the description need not explain parameters or return fields. What it covers is sufficient to invoke the tool, though it omits any routing hint among the four sibling bonus tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with every parameter documented including enum values and the state-matching rule, so the schema carries the parameter burden. The description adds no filtering syntax or format detail beyond it, making the baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Names a specific verb and resource ('find a US bank account, savings, or credit card signup bonus'), and adds a second intent ('asks which offers are worth opening'). It also states the return ordering. It stops short of naming or contrasting the siblings (get_bonus, compare_bonuses, expiring_soon), so an agent must infer which search-style 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?
'Use when a user wants to find...' gives a clear triggering context, and the mention of 'which offers are worth opening' broadens the recognized intent. However, no exclusions or alternatives are stated, so it never says when to prefer compare_bonuses or expiring_soon over this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
benefits_api_docsbenefits_examplescompare_bonusesexpiring_soonget_bonussearch_bonusesVerified US rate, savings-gap, card, CD, and product-change tools with freshness and sources.
Live US savings, CD, mortgage & HELOC rates with source + timestamp on every figure.
Live US mortgage, auto, HELOC, personal & deposit rates with evidence, plus who can join each lender
Search, compare and estimate rewards across US credit cards. Verified fees, APRs and bonuses.
Add one secure layer between your agents and this server.
