Understand declined card payments

# Auditing declined card payments

## Why a separate tool

`get_transactions` only returns successful (settled) payments. Declined payments live in a separate object, `get_failed_transactions`, with a field `get_transactions` doesn't have: a plain-language decline reason (`reasonCodeLong`) and remediation (`reasonCodeRemediation`). Always surface both to the user so they don't need to ask a follow-up — this is explicitly documented as the tool's expected behavior.

## Differences from get_transactions to know about

- `merchantName` here is the raw card-network descriptor — **not** comparable to `merchantName` on `get_transactions`, which is derived from the linked supplier's name.
- `createdAt` here reflects when the decline was recorded, whereas on `get_transactions` it reflects the settlement date (not authorization time) — the two fields aren't directly comparable across tools.
- No fixed default window: without `startDate`, coverage is the last 30 days; with `startDate`, there's no depth limit.
- ⚠️ `endDate` alone does not move that window: it only trims the last 30 days, so an `endDate` older than 30 days returns nothing. Always pass `startDate` for any period that starts more than 30 days ago.
- On `get_transactions`, `startDate`/`endDate` filter on the settlement date only: settled payments with no settlement date are excluded as soon as a date filter is set. A date-filtered list can therefore undercount a period — do not present its sum as a complete total.

## Call

```json
{
  "tool": "get_failed_transactions",
  "params": {
    "companyId": "<companyId>",
    "startDate": "2026-01-01"
  }
}
```

## Observed result

On this account, over the tested period: `{"data":[]}` — zero declined payments. This is a normal, legitimate result to report as-is ("no declined payments over this period") rather than treating it as an error or a sign the query failed.

## Currency trap

Each amount carries its own currency (`amountBilled.currency`, `amountDeclared.currency`) — there's no separate `currencyBilled`/`currencyDeclared` field. Check the currency on each record before summing. If `amountDataIssue` is present, never treat the affected amount as zero — flag it explicitly to the user.

## Example user prompts

- "Which card payments were declined this month, and why?"
- "Are there any cards with repeated declined payments?"
- "Give me the reason and fix for each of [employee]'s declined payments"