compare_bonusesUse 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 | Default |
|---|---|---|---|
| bonuses | Yes | ||
| summary | Yes |
Changes observed during successful MCP inspections.
Output schema / properties / bonuses / items / properties / bt_fee_min_usdAdded value: +{
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / bonuses / items / properties / bt_fee_pctAdded value: +{
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / bonuses / items / properties / bt_intro_apr_pctAdded value: +{
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / bonuses / items / properties / bt_intro_monthsAdded value: +{
+ "type": [
+ "number",
+ "null"
+ ]
+}Output schema / properties / bonuses / items / requiredPrevious value: -[
- "id",
- "bank_or_issuer",
- "product_name",
- "bonus_type",
- "bonus_amount_usd",
- "bonus_max_usd",
- "bonus_points",
- "annual_fee_usd",
- "requirements",
- "min_deposit_usd",
- "direct_deposit_required",
- "expiry_date",
- "states_available",
- "application_url",
- "source_url",
- "last_verified_date",
- "offer_history",
- "verification",
- "status",
- "eligibility",
- "sponsored",
- "apply_url",
- "disclosure_url"
-]New value: +[
+ "id",
+ "bank_or_issuer",
+ "product_name",
+ "bonus_type",
+ "bonus_amount_usd",
+ "bonus_max_usd",
+ "bonus_points",
+ "annual_fee_usd",
+ "bt_intro_apr_pct",
+ "bt_intro_months",
+ "bt_fee_pct",
+ "bt_fee_min_usd",
+ "requirements",
+ "min_deposit_usd",
+ "direct_deposit_required",
+ "expiry_date",
+ "states_available",
+ "application_url",
+ "source_url",
+ "last_verified_date",
+ "offer_history",
+ "verification",
+ "status",
+ "eligibility",
+ "sponsored",
+ "apply_url",
+ "disclosure_url"
+]Output schema / properties / bonuses / items / properties / bonus_type / enumPrevious value: -[
- "bank_account",
- "credit_card",
- "savings"
-]New value: +[
+ "bank_account",
+ "credit_card",
+ "savings",
+ "brokerage"
+]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 fully covered. The description adds output-level behavior (the summary highlights highest bonus / earliest expiry) but says nothing about auth needs, missing-id handling, or ordering, so it adds only modest value 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?
Two sentences, zero filler: the usage condition comes first and the return shape second. Every clause earns its place and nothing is repeated from the schema or annotations.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only comparison tool with a full output schema and complete parameter documentation, the description supplies the missing usage context and need not explain return values. Minor gaps remain around error behavior for invalid or non-existent ids, which keeps it below a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the 'ids' property already documents the 2-4 range with a concrete example. The description's phrase '2-4 bonuses' merely mirrors the schema's minItems/maxItems and adds no new syntax or format 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 concrete output: each offer's key fields plus a summary naming the highest bonus and earliest expiry, which makes the comparison purpose inferable even though the verb 'compare' lives in the title rather than the text. It distinguishes itself from single-record siblings like get_bonus by covering multiple offers, but it never names a 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?
'Use when a user is choosing between specific offers' gives a clear triggering scenario and implicitly contrasts with exploratory tools such as search_bonuses. It does not state when-not to use it or name the alternative for a single-offer lookup, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add one secure layer between your agents and this server.