The 6 read tools
Parameters and structuredContent output shape for every read tool.
All 6 tools below are read-only, idempotent, and available on both the local stdio server and the hosted remote server. None takes destructive action; none requires confirmation.
satchel_list_accounts
List every account for the authenticated customer: name, masked identifier, current balance, and which one is the main account.
Parameters: none.
structuredContent:
{
accounts: Array<{
id: number;
name: string;
iban: string;
master: boolean;
balance: { amount: number; currency: string };
}>;
count: number;
}Use the returned account ids as from_account_id / to_account_id for
satchel_move_money. For totals grouped by currency, use
satchel_get_balance instead of summing this list yourself.
satchel_get_balance
Total balance across all accounts, grouped by currency, plus the same per-account
breakdown as satchel_list_accounts.
Parameters: none.
structuredContent:
{
totals: Array<{ currency: string; amount: number }>;
accounts: Array<{ id: number; name: string; balance: { amount: number; currency: string } }>;
asOf: string; // ISO-8601 timestamp the read was taken
mode: "sandbox" | "live";
}mode states whether these numbers came from the sandbox or the live API — useful when an
assistant needs to caveat a number as sample data.
satchel_list_cards
List all payment cards: provider, masked number, currency, and status.
Parameters: none.
structuredContent:
{
cards: Array<{
id: number;
name: string;
number: string; // masked, e.g. "553012******7781"
provider: string; // e.g. "Mastercard"
currency: string;
status: "active" | "inactive" | "blocked" | "activation pending";
}>;
count: number;
}Card management (activating or blocking a card) is not available through this server — this tool is read-only in the fullest sense.
satchel_list_transactions
Recent transactions, newest first, paginated.
Parameters:
| Name | Type | Default | Notes |
|---|---|---|---|
limit | integer, 1–200 | 20 | Max transactions to return. |
page | integer, ≥ 1 | 1 | Page number. |
structuredContent:
{
transactions: Array<{
id: number;
date: string; // ISO-8601
amount: number; // ALWAYS unsigned — see "Money is always unsigned"
currency: string;
direction: "in" | "out"; // read direction from here, never from amount's sign
narrative: string; // "[withheld]" unless satchel:narratives is granted
state: string; // e.g. "EXECUTED" | "REJECTED" | "PROCESSING"
}>;
page: { page: number; records: number; totalRecords: number; totalPages: number };
}Page through until page.page === page.totalPages to cover a full period. For a
pre-computed spend overview, prefer satchel_financial_summary; for one transaction's full
detail, use satchel_get_transaction.
satchel_get_transaction
Full detail on a single transaction, by id (ids come from satchel_list_transactions).
Parameters:
| Name | Type | Notes |
|---|---|---|
id | integer, positive | Transaction / payment id, e.g. 5001. |
structuredContent:
{
id: number;
amount: number; // unsigned
currency: string;
direction?: "in" | "out"; // present when the counterparty role is known
narrative: string; // "[withheld]" by default
bankReference?: string; // masked; requires satchel:narratives
date: string;
type: string;
balanceAfter?: { amount: number; currency: string };
partner?: { name: string; role: "SENDER" | "RECIPIENT" };
fee?: { amount: number; currency: string };
rejectReason?: string | null;
}This is a richer record than the list view. Balance, fee and rejection state do not require
narratives. A masked payment reference and the counterparty name/role are returned only when
the separate satchel:narratives scope is granted. Errors with a clear not-found message if
the id doesn't exist.
satchel_financial_summary
The "intelligence" tool: pulls accounts plus up to the 200 most recent transactions and computes money in/out/net per currency, top merchants by spend, detected subscriptions, and current balances — in one call, with the arithmetic already done.
Parameters: none.
structuredContent:
{
transactionCount: number;
flows: Array<{ currency: string; in: number; out: number; net: number }>;
topMerchants: Array<{ name: string; total: number; currency: string; count: number }>;
subscriptions: Array<{
merchant: string;
occurrences: number;
averageAmount: number;
currency: string;
cadence: string; // "monthly" | "weekly" | "every ~Nd" | "recurring"
}>;
balances: Array<{ name: string; balance: { amount: number; currency: string } }>;
derived: true; // see "Derived data is labeled as derived"
narrativesIncluded: boolean;
limitations: {
requestedTransactionLimit: number;
transactionsReturned: number;
availableTransactionCount: number;
completeHistory: boolean;
merchantAndRecurringBasis: string;
advice: string;
};
conclusion: string; // one-line plain-English summary, for text-only clients
chartHint: { type: string; orientation: string; sortBy: string };
asOf: string;
mode: "sandbox" | "live";
}Money-in/out/net is computed without narratives. Merchant grouping and subscription detection
run only with satchel:narratives; otherwise those arrays are empty and
narrativesIncluded is false. When enabled, those labels are heuristics over narrative text,
not categories supplied by the institution. The output always states the up-to-200-row limit,
whether the available history is complete, and that it is informational rather than financial
advice. For raw rows use satchel_list_transactions; for plain balances use
satchel_get_balance.