> ## Documentation Index
> Fetch the complete documentation index at: https://help.mytruv.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Available tools
> Every tool your AI assistant can call through MyTruv MCP.
MyTruv MCP exposes ten read tools and three write tools. Read tools return data from your connected accounts. Write tools update how transactions are labeled and categorized - your AI assistant calls them automatically when you ask it to fix a category or rename a merchant, and they are also available to any authorized MCP client.
| Tool | What it does |
| ------------------------------------------------------------- | ---------------------------------------------------------------- |
| [accountBalances](#accountbalances) | Current balances across all connected accounts |
| [balanceHistory](#balancehistory) | Assets, liabilities, and net worth over time |
| [connectedAccountsLookup](#connectedaccountslookup) | List all connected links with status |
| [transactionHistory](#transactionhistory) | Transactions from connected bank accounts |
| [searchTransactions](#searchtransactions) | Search and filter by text, amount, category, date |
| [recurringTransactions](#recurringtransactions) | Subscriptions, bills, and recurring income |
| [spendingAnalysis](#spendinganalysis) | Spending by category, merchant, or time period |
| [incomeReport](#incomereport) | All income sources from payroll and bank data |
| [getPayrollIncome](#getpayrollincome) | Pay stub history for a specific employer |
| [getBankIncome](#getbankincome) | Bank-derived income analysis for a specific account |
| [recategorizeTransaction](#recategorizetransaction) | Change a transaction's category, merchant name, or visibility |
| [bulkRecategorizeTransactions](#bulkrecategorizetransactions) | Apply the same change to up to 200 transactions at once |
| [createCategorizationRule](#createcategorizationrule) | Create a standing rule for a merchant that applies going forward |
***
## accountBalances
Returns a snapshot of every connected account with individual balances and aggregated totals grouped by account type.
Parameters: none.
Response fields:
| Field | Type | Description |
| --------------------------------------- | -------------- | ---------------------------------------------------------------- |
| total\_accounts | integer | Number of connected accounts |
| accounts\[].id | string | Account ID - pass to `account_ids` in other tools |
| accounts\[].type | string | `CHECKING`, `SAVINGS`, `CREDIT_CARD`, `INVESTMENT`, `LOAN`, etc. |
| accounts\[].subtype | string \| null | e.g. `BROKERAGE`, `ROTH_IRA` for investment accounts |
| accounts\[].mask | string | Masked account number |
| accounts\[].nickname | string | Account display name |
| accounts\[].balances.balance | string | Current balance |
| accounts\[].balances.available\_balance | string \| null | Available balance |
| accounts\[].balances.credit\_limit | string \| null | Credit limit (credit cards only) |
| accounts\[].provider | object | Institution `{id, name, logo_url}` |
| aggregated\_balances\[] | array | Totals grouped by `type` + `currency_code`, with `account_count` |
Example prompt: *"What's my current balance across all accounts?"*
Related: [REST - Balances](/api-reference/balances/get-balances)
***
## balanceHistory
Returns historical balances across all connected accounts. Aggregates by default - filter with `account_ids` for specific accounts.
Parameters:
| Parameter | Type | Required | Default | Description |
| ------------ | ------ | -------- | ------- | -------------------------------- |
| date\_range | string | No | `3M` | `1M`, `3M`, `6M`, `1Y`, or `ALL` |
| account\_ids | string | No | All | Comma-separated account IDs |
Response fields:
| Field | Type | Description |
| --------------------------- | ------ | ------------------------ |
| time\_series\[].date | string | YYYY-MM-DD |
| time\_series\[].assets | string | Total asset value |
| time\_series\[].liabilities | string | Total liability value |
| time\_series\[].net\_worth | string | Assets minus liabilities |
| start\_date / end\_date | string | Range of the series |
Example prompt: *"Show me my net worth trend over the last 6 months."*
Related: [REST - Balance History](/api-reference/balance-history/get-balance-history)
***
## connectedAccountsLookup
Lists every account link (connection) with provider and status.
This returns `id` for each link. To get the `link_id` value used by `getPayrollIncome` and `getBankIncome`, call [`incomeReport`](#incomereport) and use `employments[].link_id` from there - that field is curated for the income flow.
Parameters: none.
Response fields:
| Field | Type | Description |
| -------------------------------------------------- | ------ | ------------------------------------------- |
| results\[].id | string | Unique link identifier |
| results\[].provider | object | Provider `{id, name, logo_url}` |
| results\[].data\_source | string | `payroll` or `financial_accounts` |
| results\[].status | string | `done`, `session_expired`, etc. |
| results\[].initial\_product\_type | string | Product the link was originally created for |
| results\[].created\_at / updated\_at / deleted\_at | string | Timestamps |
Example prompt: *"What accounts do I have connected?"*
Related: [REST - Account Links](/api-reference/links/get-links)
***
## transactionHistory
Fetches transactions from all connected bank accounts and combines them into a single report. Descriptions are anonymized for privacy.
Parameters:
| Parameter | Type | Required | Default | Description |
| ---------- | ------- | -------- | ------- | ------------------------------------ |
| days | integer | No | `30` | Number of days to retrieve (max 365) |
| categories | string | No | All | Comma-separated category names |
Response fields:
| Field | Type | Description |
| ------------------------------- | -------------- | ------------------------------------------------------------------------ |
| count | integer | Total number of transactions |
| accounts\[] | array | Bank accounts with balances (same shape as `accountBalances.accounts[]`) |
| transactions\[].id | string | Transaction ID |
| transactions\[].account\_id | string | Source account ID |
| transactions\[].amount | string | Transaction amount |
| transactions\[].currency\_code | string | e.g. `USD` |
| transactions\[].categories | array | Display category names (e.g. `["Food & Dining", "Restaurants"]`) |
| transactions\[].category\_slugs | array | Snake-case slugs for the same categories |
| transactions\[].description | string | Description (personal names anonymized, e.g. `R***a K*****a`) |
| transactions\[].merchant\_name | string \| null | Cleaned-up merchant name |
| transactions\[].memo | string \| null | Memo line if present |
| transactions\[].status | string | `POSTED` or `PENDING` |
| transactions\[].type | string | `CREDIT` (money in) or `DEBIT` (money out) |
| transactions\[].posted\_at | string \| null | When the transaction posted (null while pending) |
| transactions\[].transacted\_at | string | When the purchase actually happened |
Example prompt: *"Show me all my grocery transactions from the last 2 weeks."*
Related: [REST - Transactions](/api-reference/transactions/get-transactions)
***
## searchTransactions
More powerful than `transactionHistory` for targeted lookups. Supports text search, amount ranges, type filtering, and pagination.
Parameters:
| Parameter | Type | Required | Default | Description |
| ----------------- | ------- | -------- | ------- | ------------------------------------------------- |
| query | string | No | - | Text in descriptions and memos (case-insensitive) |
| min\_amount | number | No | - | Minimum absolute amount |
| max\_amount | number | No | - | Maximum absolute amount |
| transaction\_type | string | No | All | `DEBIT` or `CREDIT` |
| categories | string | No | All | Comma-separated category names |
| days | integer | No | `90` | Days to look back (max 365) |
| sort\_by | string | No | `date` | `date` or `amount` |
| sort\_order | string | No | `desc` | `desc` or `asc` |
| limit | integer | No | `20` | Results per page (max 50) |
| offset | integer | No | `0` | Pagination offset |
Response fields:
| Field | Type | Description |
| --------------- | ------- | ------------------------------------------------- |
| total\_matches | integer | Total matching transactions before pagination |
| transactions\[] | array | Same shape as `transactionHistory.transactions[]` |
Example prompts:
* *"Find all transactions over \$500 in the last 90 days."*
* *"How much did I spend at coffee shops?"*
***
## recurringTransactions
Detects recurring patterns from bank data and splits them into inflows (income) and outflows (expenses).
Parameters:
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | -------- | ------------------------------------------- |
| status | string | No | `active` | `active`, `inactive`, `irregular`, or `all` |
Top-level shape: `{recurring_transactions: {outflows: [...], inflows: [...]}}` .
Outflow fields:
| Field | Type | Description |
| ---------------------------------------------------------------- | -------------- | ------------------------------------------------------------------------------------ |
| source\_id / source\_name | string | Stable ID and human label for the recurring source |
| account\_id | string | Account the recurring transaction posts to |
| categories | array | Display category names |
| description | string | Representative description |
| frequency | string | `W` weekly, `BW` biweekly, `SM` semi-monthly, `M` monthly, `Q` quarterly, `Y` yearly |
| average\_amount / median\_amount / last\_amount | string | Stats across detected occurrences |
| status | string | `active`, `inactive`, or `irregular` |
| first\_detected / last\_transaction\_date / next\_expected\_date | string | Detection window and forecast |
| logo\_url | string \| null | Brand logo when MyTruv has one |
| historical\_transactions\[] | array | The individual transactions used to detect this stream |
Inflow fields: same shape as outflow plus `income_type` (e.g. `PAYCHECK`).
Example prompt: *"Show me all my active subscriptions."*
***
## spendingAnalysis
Spending breakdowns grouped by category, merchant, or time period, with trend comparisons.
Parameters:
| Parameter | Type | Required | Default | Description |
| -------------------- | ------ | -------- | -------------- | ---------------------------------------------------------------------------------------------------------- |
| group\_by | string | Yes | - | `category`, `merchant`, or `time_period` |
| time\_period | string | Yes | - | `day`, `week`, `month`, `quarter`, or `year` |
| start\_date | string | No | 3 periods back | Start date (YYYY-MM-DD) |
| end\_date | string | No | Today | End date (YYYY-MM-DD) |
| account\_ids | string | No | All | Comma-separated account IDs |
| categories | string | No | All | Comma-separated category names |
| link\_id | string | No | All links | Filter to a specific link |
| min\_total\_amount | number | No | `50.00` | Group amounts below this threshold as `Other` |
| secondary\_group\_by | string | No | - | Only when `group_by=time_period`: nest a top-10 `category` or `merchant` breakdown inside each time bucket |
`INVESTMENT`-type accounts (brokerage, crypto, IRA) are always excluded - stock buys, reinvestments, and margin interest are not personal spending.
Response fields (only the field matching `group_by` is populated; the other two stay `null`):
| Field | Type | Description |
| ---------------------------------------------- | -------------- | ------------------------------------------------------ |
| spending.by\_category\[].category | string | Category name |
| spending.by\_category\[].total\_amount | string | Total spent in the category |
| spending.by\_category\[].transaction\_count | integer | Number of transactions |
| spending.by\_category\[].percentage\_of\_total | string | Share of total spending |
| spending.by\_category\[].trend | string \| null | % change vs prior period |
| spending.by\_category\[].subcategories\[] | array | Nested `{name, amount, count}` (>= `min_total_amount`) |
| spending.by\_category\[].time\_series\[] | array | Per-period `{start_date, end_date, amount, count}` |
| spending.by\_category\[].largest\_transaction | object | The biggest single transaction in this group |
| spending.by\_merchant\[] | array | Same shape but keyed on `merchant_name` |
| spending.by\_time\_period\[] | array | Same shape but keyed on `period_start` / `period_end` |
| summary.total\_spending | string | Total across range |
| summary.average\_daily\_spending | string | Average per day |
| summary.average\_monthly\_spending | string | Average per month |
| summary.total\_transactions | integer | Transactions analyzed |
| summary.unique\_merchants | integer | Distinct merchants in range |
| summary.top\_category / top\_merchant | string | Highest-spending category and merchant |
| request\_id | string | Request identifier (useful for debugging) |
| created\_at | string | ISO timestamp the analysis was run |
Example prompts:
* *"Break down my spending by category this month."*
* *"Compare my spending month over month for the last quarter."*
Related: [REST - Spending](/api-reference/spending/get-spending)
***
## incomeReport
Aggregates income from all connected sources and deduplicates entries that appear in both payroll and bank data. Returns one record per employer or income source.
Parameters: none.
Response fields:
| Field | Type | Description |
| -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------- |
| employments\[].link\_id | string | Use with `getPayrollIncome` or `getBankIncome` |
| employments\[].data\_source | string | `payroll` or `financial_accounts` |
| employments\[].provider | string | Provider slug (e.g. `rippling`, `chase_bank`) |
| employments\[].company | object | `{name, address, phone, ein}` for payroll; `{name}` for bank-derived |
| employments\[].income | string | Income amount |
| employments\[].income\_unit | string | `YEARLY`, `MONTHLY`, etc. |
| employments\[].pay\_rate | string | Per-pay-period amount |
| employments\[].pay\_frequency | string | `W` weekly, `BW` biweekly, `SM` semi-monthly, `M` monthly |
| employments\[].is\_active | boolean | Currently active |
| employments\[].job\_title / job\_type | string | Title and `F` (full-time) / `P` (part-time) etc. |
| employments\[].start\_date / end\_date | string \| null | Employment range |
| employments\[].bank\_income\_category | string \| null | Set when `data_source=financial_accounts` |
| employments\[].statement\_count | integer | Pay statements available (payroll only) |
| summary | object | `{total_employments, payroll_sources, bank_sources, deduplicated_bank_sources, connected_bank_links}` |
Example prompt: *"What are my income sources?"*
Related: [REST - Income](/api-reference/income/get-income)
***
## getPayrollIncome
Full payroll income report with pay stub history for a single connected payroll account - earnings, deductions, and year-to-date totals for the last 90 days.
Use the `link_id` from [incomeReport](#incomereport) - do not guess this value.
Parameters:
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------- |
| link\_id | string | Yes | - | `link_id` from `incomeReport` |
Response fields:
| Field | Type | Description |
| --------------------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------- |
| status | string | `done` when the report is ready |
| provider / data\_source | string | Provider slug, always `payroll` |
| employments\[].company | object | `{name, address, phone, ein}` |
| employments\[].is\_active / job\_title / job\_type | various | Role status and metadata |
| employments\[].start\_date / end\_date / employed\_in\_role | string | Employment timeline |
| employments\[].statements\[].pay\_date | string | Payment date |
| employments\[].statements\[].period\_start / period\_end | string | Pay period covered |
| employments\[].statements\[].gross\_pay / net\_pay | string \| null | Per-statement totals (older statements may be null) |
| employments\[].statements\[].gross\_pay\_ytd / net\_pay\_ytd | string \| null | Year-to-date totals |
| employments\[].statements\[].regular / overtime / bonus / commission / other\_pay | string \| null | Earnings breakdown |
| employments\[].statements\[].earnings\[] | array | `{name, amount, category, rate, units}` line items |
| employments\[].statements\[].deductions\[] | array | `{name, amount, category}` (taxes, retirement, benefits) |
| employments\[].annual\_income\_summary\[] | array | Per-year `{year, regular, bonus, commission, overtime, other_pay, net_pay, gross_pay}` |
Example prompt: *"Show me my recent pay stubs from Acme Corp."*
***
## getBankIncome
Income analysis derived from bank transactions for a single connected account. Identifies income streams with historical averages, pay frequency, and the transactions used for detection.
Use the `link_id` from [incomeReport](#incomereport) - do not guess this value.
Parameters:
| Parameter | Type | Required | Default | Description |
| --------- | ------ | -------- | ------- | ----------------------------- |
| link\_id | string | Yes | - | `link_id` from `incomeReport` |
Response fields:
| Field | Type | Description |
| ------------------------------------- | ------- | ------------------------------------------ |
| income\_sources\[].name | string | Source name (e.g. employer) |
| income\_sources\[].category | string | Income category |
| income\_sources\[].average\_amount | string | Historical average per payment |
| income\_sources\[].frequency | string | Detected frequency |
| income\_sources\[].transaction\_count | integer | Transactions analyzed |
| income\_sources\[].transactions\[] | array | Individual transactions used for detection |
Example prompt: *"Analyze the income deposits in my Chase checking account."*
***
## recategorizeTransaction
Applies an override to a single transaction. Changes the category, renames the merchant as it appears in MyTruv, hides it from spending totals, or flags it as recurring or an internal transfer. Only the fields you pass are changed.
After writing, the response surfaces similar transactions from the same merchant so you can optionally extend the change.
Pass `confirmed=false` (or omit it) on your first call when the user names only a merchant without pointing to a specific transaction. The tool returns candidates without writing. Once the user confirms which transaction they mean, call again with `confirmed=true`.
Parameters:
| Parameter | Type | Required | Default | Description |
| ------------------------ | -------------- | -------- | ------- | ----------------------------------------------------------------------------------------- |
| transaction\_id | string | Yes | - | ID from `searchTransactions` or `transactionHistory` |
| category | string \| null | No | - | Display name (e.g. `"Groceries"`) or slug (e.g. `"groceries"`) |
| merchant\_name | string \| null | No | - | Rename the merchant on this transaction |
| hide | bool \| null | No | - | `true` hides from spending; `false` un-hides |
| mark\_recurring | bool \| null | No | - | `true` flags as a recurring bill or subscription |
| mark\_internal\_transfer | bool \| null | No | - | `true` flags as a transfer between your own accounts |
| confirmed | bool | No | `false` | Set `true` only after the user has confirmed which transaction they mean |
| allow\_custom | bool | No | `false` | Set `true` only if the user insists on a category name that does not exist in the catalog |
Response (write succeeded):
| Field | Type | Description |
| ------------------------ | ------- | ------------------------------------------------------------------------------------------- |
| override | object | The merged override state applied to the transaction |
| merchant\_name | string | The merchant matched |
| similar\_transactions\[] | array | Up to 20 other transactions from the same merchant (last 90 days) |
| total\_similar | integer | Total count of other matching transactions |
| preview\_truncated | bool | `true` if there are more than 20 similar transactions |
| rule\_exists | bool | Whether a standing rule already exists for this merchant |
| next\_actions\[] | array | Suggested follow-up calls (e.g. `bulkRecategorizeTransactions`, `createCategorizationRule`) |
Response (confirmation required):
| Field | Type | Description |
| ------------------------ | ------- | -------------------------------------------------------------- |
| status | string | `"confirmation_required"` |
| merchant\_name | string | The merchant matched |
| similar\_transactions\[] | array | Candidate transactions to show the user |
| total\_similar | integer | Total count |
| message | string | Instructions to present candidates and ask the user to confirm |
Example prompts:
* *"Change the category on that Costco charge to Groceries."*
* *"Rename that AMZN MKTPL transaction to Amazon."*
* *"Hide this transfer from my spending."*
***
## bulkRecategorizeTransactions
Applies the same override to multiple transactions at once. Intended as a follow-up to `recategorizeTransaction` when the user agrees to extend the change to similar past transactions. Accepts up to 200 transaction IDs. For applying a change to all future transactions from a merchant, use `createCategorizationRule` instead.
All IDs are verified as belonging to the authenticated user before any writes are made. If any ID is not found, the entire call fails with an error.
Parameters:
| Parameter | Type | Required | Default | Description |
| ------------------------ | -------------- | -------- | ------- | ------------------------------------------------------------------ |
| transaction\_ids | string | Yes | - | Comma-separated transaction IDs (max 200) |
| category | string \| null | No | - | Display name or slug (same semantics as `recategorizeTransaction`) |
| merchant\_name | string \| null | No | - | Rename the merchant on all listed transactions |
| hide | bool \| null | No | - | Hide or un-hide the transactions |
| mark\_recurring | bool \| null | No | - | Flag or un-flag as recurring |
| mark\_internal\_transfer | bool \| null | No | - | Flag or un-flag as an internal transfer |
| allow\_custom | bool | No | `false` | Same semantics as `recategorizeTransaction` |
At least one of `category`, `merchant_name`, `hide`, `mark_recurring`, or `mark_internal_transfer` must be provided.
Response:
| Field | Type | Description |
| ------------------- | ------- | ------------------------------------------- |
| applied\_count | integer | Number of transactions successfully updated |
| transaction\_ids\[] | array | The input IDs echoed back |
Example prompt: *"Apply that same Groceries category to the other Costco transactions you found."*
***
## createCategorizationRule
Creates a standing rule so that future transactions from a merchant are automatically categorized. By default the rule also applies retroactively to all past transactions from that merchant. Use this as a follow-up after `recategorizeTransaction` when the user wants the change to stick permanently.
If a rule already exists for the merchant, the tool returns an error with the existing rule ID. Rules can be managed in MyTruv settings; editing or deleting a rule via the MCP is not yet supported.
Parameters:
| Parameter | Type | Required | Default | Description |
| ------------------------ | -------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| merchant\_name | string | Yes | - | The merchant to match (case-insensitive, max 500 characters) |
| category | string \| null | No | - | Display name or slug to apply to matching transactions |
| custom\_merchant\_name | string \| null | No | - | Rename the merchant across all matching transactions |
| hide | bool \| null | No | - | Hide matching transactions from spending views |
| mark\_recurring | bool \| null | No | - | Mark matching transactions as recurring |
| mark\_internal\_transfer | bool \| null | No | - | Mark matching transactions as internal transfers |
| apply\_to\_past | bool | No | `true` | `true` applies retroactively to all existing transactions; `false` applies only to transactions dated after the rule is created |
| allow\_custom | bool | No | `false` | Same semantics as `recategorizeTransaction` |
At least one of `category`, `custom_merchant_name`, `hide`, `mark_recurring`, or `mark_internal_transfer` must be provided.
Response:
| Field | Type | Description |
| ------------------------------ | -------------- | ------------------------------------------------------ |
| rule.rule\_id | string | UUID of the new rule |
| rule.match\_merchant\_name | string | The merchant name being matched |
| rule.custom\_category | string \| null | Category applied by the rule |
| rule.custom\_merchant\_name | string \| null | Merchant rename applied by the rule |
| rule.is\_hidden | bool \| null | Whether matching transactions are hidden |
| rule.is\_recurring | bool \| null | Whether matching transactions are flagged recurring |
| rule.is\_internal\_transfer | bool \| null | Whether matching transactions are flagged as transfers |
| rule.scope | string | `ALL` (retroactive) or `FORWARD_ONLY` |
| rule.created\_at / updated\_at | string | ISO timestamps |
Example prompts:
* *"Always put Costco in Groceries going forward."*
* *"Set a rule so all Venmo transactions are marked as internal transfers."*
***
## Next steps