Cards

Search the card catalog and get a card, comparison, or offer recommendation grounded in a member's own wallet.

get_best_card

Best card in the user's wallet for a spending category (dining, groceries, gas, travel, rent, ...) or a specific merchant -- pass at least one of category or merchant; amount (dollars) is optional.

Scope	Quota
`miles:read`	standard

Name	Type	Description
`category`	`string`	The one key that names what is being bought. `other` when no key fits and the base rate applies. The brand goes in `merchant`.
`merchant`	`string`	A specific merchant (e.g. `"Costco"`).
`amount`	`number`	Purchase amount in dollars, for the receipt's dollar line; a non-positive value is treated as absent.
`international`	`boolean`	Set to true when the purchase happens OUTSIDE the United States: the user names a foreign city or country ('in Tokyo', 'in Europe'), says abroad/overseas, or is on an international trip. Ranks by net return after foreign transaction fees and drops U.S.-only earning categories (Business Gold's 4X is 'U.S. purchases at restaurants' and earns nothing extra in Tokyo). Default false. Leave it off for domestic spending.
`cards`	`string[]`	Cards the user says they hold; ones the saved wallet lacks are ranked as held (`stated_cards`).
`channel`	`string`	How the purchase is made, when the person says so: `online` for a website or online order, `in_app` for a merchant's own app, `mobile_wallet` for Apple Pay or Google Pay, `physical_card` for the physical card, `direct` for booked directly with the airline or hotel. Omit otherwise.
`portal`	`string`	The booking portal the purchase goes through, when the person names one. Omit otherwise.
`housing`	`string`	With category `rent`: `mortgage` for a mortgage payment, `rent` for rent. Omit otherwise.
`merchant_role`	`string`	`provider` sells the category itself (restaurant, airline, hotel); `reseller` resells travel or experiences (day passes, tours); `payment_platform` is a payment app. Omit if unsure.
`paid_through`	`string`	Third-party payment platform named by the person. Keep the seller in `merchant` and name the payment platform here. Omit otherwise.
`redemption_basis`	`string`	The member's own stated way of redeeming, for this conversation. Omit unless the member said how they redeem.

get_card_info

Full details for a credit card PRODUCT: fees, earning rates, credits, benefits, transfer partners, sign-up bonus.

Scope	Quota
`miles:read`	standard

Name	Type	Required	Description
`card_name`	`string`		Catalog product name, fuzzy-matched (`"Amex Plat"` resolves). Send this or `wallet_id`, not both; `wallet_id` wins when both arrive.
`wallet_id`	`string`		A `cc_N` wallet entry id from `get_wallet_cards`; resolves to the product that entry holds. Takes only the `cc_N` shape: a product name here is refused, and an id with no entry is refused rather than fuzzy-matched.

get_product_changes

Upgrade and downgrade paths for a wallet card -- the natural next question after analyze_keep_cancel. Wallet-aware: results reflect which products you already hold.

Scope	Quota
`miles:read`	standard

Name	Type	Required	Description
`card_name`	`string`	required	Name of a card in the user's wallet to list upgrade and downgrade paths for.

get_top_offers

Current top sign-up bonuses, optionally filtered by card type (personal/business), ranked by Miles's first-year value.

Scope	Quota
`miles:read`	standard

Name	Type	Description
`card_type`	`string`	Filter to `"personal"` or `"business"` cards; omit for both.
`member`	`string`	On a Household Profiles account, the household member to rank offers for; omit to keep any offer some member can apply for. A household member's name; a name matching no member is refused, not guessed.
`annual_fee_max`	`number`	Maximum recorded annual fee in dollars; 0 means no-fee offers only. Offers with unknown fees are excluded.
`recent_denial_reason`	`string`	A recent card denial the person states, by reason; every issuer then reads `may_be_restricted`, never open.
`hard_inquiries_6m`	`integer`	Hard inquiries in the last 6 months, when stated; read by issuer inquiry limits.

get_wallet_complement

Recommends NEW cards to get -- fills gaps in the wallet, not a keep/cancel review of cards already held. Finds orphaned points needing a companion card, weak spending categories, missing transfer ecosystems, and network gaps, then ranks up to 5 candidate cards with gap-fill reasons, ongoing value, and sign-up bonus. Each recommendation carries inline eligibility annotations (5/24, 6/24, Amex velocity limits) and portfolio rules (e.g. one Sapphire product at a time); results are filtered to the wallet's card type (personal/business) automatically.

Scope	Quota
`miles:read`	standard

Name	Type	Description
`focus`	`string`	`"earning"` narrows to category-multiplier gaps, `"ecosystem"` to new transfer-partner access; omit for a comprehensive analysis.
`card_name`	`string`	Find complements for one specific wallet card instead of the whole wallet.
`check_eligibility`	`boolean`	When true, drop cards the user cannot currently apply for instead of just annotating them. Already on by default whenever the wallet is non-empty.
`member`	`string`	On a Household Profiles account, the household member whose eligibility judges each candidate; omit to keep any candidate some member can apply for. A household member's name; a name matching no member is refused, not guessed.
`preferred_programs`	`string[]`	Loyalty programs the user has explicitly named as preferences, any spelling. A card that earns one, or transfers to one, is nudged up the ranking and says so in its gap-fill reasons: a tie-breaker, not a filter. Never infer these from the wallet; unrecognized names come back in `preferred_programs_unmatched`.
`recent_denial_reason`	`string`	A recent card denial the person states, by reason; every issuer then reads `may_be_restricted`, never open.
`hard_inquiries_6m`	`integer`	Hard inquiries in the last 6 months, when stated; read by issuer inquiry limits.

search_cards

Search the 180+ card dataset by issuer, fees, rewards program, airline/hotel affiliation, or bonus spending categories.

Scope	Quota
`miles:read`	standard

Name	Type	Description
`spending_categories`	`string[]`	Bonus spending categories the card should earn well in, as a list of category names (e.g. `["dining", "groceries"]`), not one comma-joined string.
`issuer`	`string`	Limit results to one issuer (e.g. `"Chase"`, `"Amex"`).
`card_type`	`string`	Limit results to `"Personal"` or `"Business"` cards.
`max_annual_fee`	`integer`	Highest annual fee to include, in whole dollars; `0` means no-annual-fee cards only.
`rewards_program`	`string`	Limit results to cards earning one rewards program or currency (e.g. `"Chase Ultimate Rewards"`). Applied after the search, so the response notes when fewer than `limit` cards matched.
`airline`	`string`	Limit results to cards affiliated with one airline (e.g. `"United"`).
`hotel`	`string`	Limit results to cards affiliated with one hotel program (e.g. `"Hyatt"`).
`has_signup_bonus`	`boolean`	When true, keep only cards currently offering a sign-up bonus.
`limit`	`integer`	Maximum number of cards to return. Default 10.
`member`	`string`	On a Household Profiles account, the household member whose application eligibility filters the result; omit to keep any card some member can apply for. A household member's name; a name matching no member is refused, not guessed.
`is_student`	`boolean`	True only when the user said they are a student. Student cards are hidden otherwise.