> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai2fin.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Transaction tools for AI assistants
> AI2Fin MCP transaction tools to query expenses, summarise tax deductions, analyse spending by category and merchant, compare periods, and bulk-categorise transactions from ChatGPT, Claude or Cursor.
# Transaction Tools
The AI2Fin MCP server exposes a set of transaction tools so your AI assistant can query expenses and income, surface tax-deductible spending, analyse where your money goes, and tidy up categorisation in bulk — all using natural language.
Every request is scoped to your own account. Tools only ever return your own transactions, and only when called with your valid credentials.
***
## get\_transactions
Retrieves transactions with AI analysis (cached - no re-analysis).
### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ----------------------------------------- |
| `startDate` | string | No | Start date (ISO 8601, e.g., "2025-01-01") |
| `endDate` | string | No | End date (ISO 8601) |
| `isTaxDeductible` | boolean | No | Filter tax deductible only |
| `categoryId` | string | No | Filter by category ID |
| `minAmount` | number | No | Minimum amount |
| `maxAmount` | number | No | Maximum amount |
| `limit` | number | No | Max results (default: 100) |
### Response fields
Each transaction in the response includes the fields you'd expect to work with:
| Field | Description |
| ----------------------- | ------------------------------------------------ |
| `id` | Transaction identifier |
| `description` | What the transaction was for |
| `amount` | Amount (negative = expense, positive = income) |
| `date` | Transaction date (ISO 8601) |
| `primaryType` | `expense`, `income`, or `transfer` |
| `secondaryType` | `bill`, `one-time expense`, or `capital expense` |
| `isTaxDeductible` | Whether the transaction is flagged as deductible |
| `taxDeductionReason` | Plain-language reason it qualifies |
| `businessUsePercentage` | Business-use portion (0–100) |
| `category` | Assigned category (`id`, `name`, `color`) |
| `merchant` | Merchant or payee name |
| `notes` | Your notes on the transaction |
Tax and categorisation results are returned ready to use — there's no extra analysis step on retrieval, so responses come back fast.
### Example Request
```json theme={null}
{
"startDate": "2025-01-01",
"endDate": "2025-03-31",
"isTaxDeductible": true,
"limit": 50
}
```
### Example Response
```json theme={null}
{
"success": true,
"data": {
"transactions": [
{
"id": "clx123abc",
"transactionId": "txn_unique_id",
"description": "Office Supplies - Staples",
"amount": -125.50,
"date": "2025-02-15T00:00:00.000Z",
"primaryType": "expense",
"secondaryType": "one-time expense",
"isTaxDeductible": true,
"taxDeductionReason": "Business expense - office supplies",
"businessUsePercentage": 100,
"category": {
"id": "cat_office",
"name": "Office Expenses",
"color": "#4CAF50"
},
"merchant": "Staples",
"recurring": false
}
],
"count": 23,
"filters": {
"startDate": "2025-01-01",
"endDate": "2025-03-31",
"isTaxDeductible": true
}
}
}
```
***
## get\_tax\_deductible\_summary
Summarizes tax deductible transactions grouped by category.
### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ----------- |
| `startDate` | string | No | Start date |
| `endDate` | string | No | End date |
### Example Request
```json theme={null}
{
"startDate": "2025-01-01",
"endDate": "2025-12-31"
}
```
### Example Response
```json theme={null}
{
"success": true,
"data": {
"totalCount": 156,
"totalAmount": 24532.75,
"byCategory": {
"Office Expenses": {
"count": 23,
"total": 3250.50
},
"Travel - Vehicle": {
"count": 45,
"total": 12500.00
},
"Professional Services": {
"count": 12,
"total": 8782.25
}
},
"dateRange": {
"startDate": "2025-01-01",
"endDate": "2025-12-31"
}
}
}
```
***
## create\_transaction
Creates a new transaction.
### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | --------------------------------------------------- |
| `description` | string | Yes | Transaction description |
| `amount` | number | Yes | Amount (negative for expenses, positive for income) |
| `date` | string | Yes | Date (ISO 8601) |
| `primaryType` | string | Yes | "expense", "income", or "transfer" |
| `secondaryType` | string | No | "bill", "one-time expense", "capital expense" |
| `isTaxDeductible` | boolean | No | Is tax deductible (default: false) |
| `categoryId` | string | No | Category ID |
| `merchant` | string | No | Merchant name |
| `notes` | string | No | Additional notes |
### Example Request
```json theme={null}
{
"description": "Office Rent - March 2025",
"amount": -2500.00,
"date": "2025-03-01",
"primaryType": "expense",
"secondaryType": "bill",
"isTaxDeductible": true,
"merchant": "Property Management Co",
"notes": "Monthly office rent"
}
```
### Example Response
```json theme={null}
{
"success": true,
"data": {
"transaction": {
"id": "clx789xyz",
"transactionId": "txn_new_unique",
"description": "Office Rent - March 2025",
"amount": -2500.00,
"date": "2025-03-01T00:00:00.000Z",
"primaryType": "expense",
"secondaryType": "bill",
"isTaxDeductible": true,
"merchant": "Property Management Co",
"notes": "Monthly office rent",
"processed": true,
"createdAt": "2025-03-01T10:30:00.000Z"
}
}
}
```
***
## trigger\_smart\_categorization
Categorises uncategorised or specified transactions for you, automatically assigning the most likely category to each.
Transactions that have already been categorised are reused as-is for speed. Set `force: true` only when you want everything re-evaluated from scratch.
### Parameters
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ------------------------------------------------------------ |
| `transactionIds` | string\[] | No | Specific transaction IDs (if empty, processes uncategorized) |
| `force` | boolean | No | Force re-categorization (default: false) |
### Example Request
```json theme={null}
{
"transactionIds": ["clx123abc", "clx456def"],
"force": false
}
```
### Example Response
```json theme={null}
{
"success": true,
"data": {
"processed": 2,
"categorized": 2,
"failed": 0,
"results": [
{
"transactionId": "clx123abc",
"categoryId": "cat_office",
"categoryName": "Office Expenses",
"confidence": 0.95
},
{
"transactionId": "clx456def",
"categoryId": "cat_travel",
"categoryName": "Travel - Vehicle",
"confidence": 0.89
}
]
}
}
```
***
## get\_category\_spending\_summary
NEW - Analytics Tool
Analyzes spending breakdown by category for a date range. Perfect for answering "Where does my money go?" questions.
### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | --------------------------------------- |
| `startDate` | string | Yes | Start date (ISO 8601) |
| `endDate` | string | Yes | End date (ISO 8601) |
| `minAmount` | number | No | Minimum transaction amount to include |
| `limit` | number | No | Max categories to return (default: 100) |
### Example Response
```json theme={null}
{
"success": true,
"data": {
"totalSpending": 3876.42,
"totalTransactions": 143,
"uncategorizedAmount": 123.45,
"uncategorizedPercentage": 3.18,
"categories": [
{
"categoryName": "Groceries",
"total": 1245.67,
"count": 18,
"percentage": 32.15,
"averageTransaction": 69.20
},
{
"categoryName": "Dining Out",
"total": 876.43,
"count": 24,
"percentage": 22.62,
"averageTransaction": 36.52
}
]
}
}
```
***
## get\_top\_merchants
NEW - Analytics Tool
Ranks merchants by total spending. Answers "Where do I spend the most?"
### Parameters
| Parameter | Type | Required | Description |
| ----------- | ------ | -------- | ------------------------------------- |
| `startDate` | string | Yes | Start date (ISO 8601) |
| `endDate` | string | Yes | End date (ISO 8601) |
| `limit` | number | No | Max merchants to return (default: 10) |
### Example Response
```json theme={null}
{
"success": true,
"data": {
"totalSpending": 3876.42,
"merchants": [
{
"merchant": "Woolworths",
"total": 487.23,
"count": 12,
"percentage": 12.57,
"averageTransaction": 40.60,
"category": "Groceries"
}
]
}
}
```
***
## compare\_spending\_periods
NEW - Analytics Tool
Compares spending between two time periods (e.g., this month vs last month).
### Parameters
| Parameter | Type | Required | Description |
| -------------- | ------ | -------- | -------------------------------------------------------- |
| `period1Start` | string | Yes | Period 1 start date |
| `period1End` | string | Yes | Period 1 end date |
| `period2Start` | string | Yes | Period 2 start date |
| `period2End` | string | Yes | Period 2 end date |
| `groupBy` | string | No | "total", "category", or "merchant" (default: "category") |
### Example Response (Total Comparison)
```json theme={null}
{
"success": true,
"data": {
"period1": {
"start": "2024-10-01",
"end": "2024-10-31",
"total": 3876.42,
"count": 143
},
"period2": {
"start": "2024-09-01",
"end": "2024-09-30",
"total": 3234.21,
"count": 128
},
"difference": 642.21,
"percentChange": 19.86,
"trend": "increased"
}
}
```
***
## bulk\_categorize\_transactions
NEW - Bulk Operation
Updates category for multiple transactions at once. Great for "Categorize all Uber as Transport" requests.
### Parameters
| Parameter | Type | Required | Description |
| ------------------ | --------- | -------- | ----------------------------------------- |
| `transactionIds` | string\[] | No\* | Specific transaction IDs |
| `categoryId` | string | Yes | Category to assign |
| `filterByMerchant` | string | No\* | Merchant name filter (alternative to IDs) |
| `filterStartDate` | string | No | Start date for filter |
| `filterEndDate` | string | No | End date for filter |
\*Either `transactionIds` OR `filterByMerchant` required
### Example Response
```json theme={null}
{
"success": true,
"data": {
"updatedCount": 15,
"categoryName": "Transport",
"message": "✅ Updated 15 transaction(s) to category \"Transport\""
}
}
```
***
## bulk\_update\_transactions
NEW - Bulk Operation
Updates multiple fields for multiple transactions simultaneously.
### Parameters
| Parameter | Type | Required | Description |
| ---------------- | --------- | -------- | ---------------------------- |
| `transactionIds` | string\[] | Yes | Transaction IDs to update |
| `updates` | object | Yes | Fields to update (see below) |
**Updates Object:**
* `categoryId` (string): New category
* `isTaxDeductible` (boolean): Tax status
* `businessUsePercentage` (number): Business use 0-100
* `notes` (string): Add notes
### Example Response
```json theme={null}
{
"success": true,
"data": {
"updatedCount": 8,
"fields": ["categoryId", "isTaxDeductible"],
"message": "✅ Updated 8 transaction(s)"
}
}
```
***
## find\_duplicate\_transactions
NEW - Bulk Operation
Finds likely duplicate payments so you can catch double charges and accidental repeat payments.
### Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | -------------------------------------------------------------- |
| `startDate` | string | Yes | Start date to search |
| `endDate` | string | Yes | End date to search |
| `toleranceHours` | number | No | How close in time two charges must be to count as duplicates |
| `amountTolerance` | number | No | How close in amount two charges must be to count as duplicates |
### Example Response
```json theme={null}
{
"success": true,
"data": {
"duplicateGroupsCount": 2,
"duplicateGroups": [
{
"merchant": "Netflix",
"amount": 15.99,
"count": 2,
"totalAmount": 31.98,
"transactions": [
{
"id": "txn_1",
"date": "2024-10-15T15:45:00Z",
"merchant": "Netflix",
"amount": -15.99
},
{
"id": "txn_2",
"date": "2024-10-15T23:23:00Z",
"merchant": "Netflix",
"amount": -15.99
}
]
}
],
"potentialSavings": 15.99
}
}
```
***
## analyze\_transaction\_categorization
AI Analysis Tool
Suggests the best category for a transaction, along with a confidence score and a plain-language explanation of why it fits.
### Parameters
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | ----------------------------------------------- |
| `transactionId` | string | Yes | Transaction to analyze |
| `merchant` | string | No | Merchant override (defaults to stored merchant) |
| `description` | string | No | Description override |
| `amount` | number | No | Amount override |
### Example Response
```json theme={null}
{
"success": true,
"data": {
"transactionId": "txn_123",
"analysis": {
"suggestedCategory": "Office Expenses",
"confidence": 0.92,
"reasoning": "Matches previous office supply purchases",
"alternativeCategories": ["Supplies", "Stationery"]
}
}
}
```
***
## analyze\_transaction\_tax\_deductibility
AI Analysis Tool
Assesses whether a transaction is tax deductible, estimates the business-use portion, lists the documentation you should keep, and flags GST implications.
### Parameters
| Parameter | Type | Required | Description |
| --------------- | ------ | -------- | ---------------------- |
| `transactionId` | string | Yes | Transaction to analyse |
### Example Response
```json theme={null}
{
"success": true,
"data": {
"analysis": {
"isTaxDeductible": true,
"businessUsePercentage": 80,
"taxCategory": "Office Expenses",
"documentationRequired": ["Receipt", "Business purpose"],
"warnings": [],
"suggestions": []
}
}
}
```
***
## apply\_analysis\_to\_transaction
AI Helper
Applies the approved recommendations to the transaction in one step: category, tax-deductible status, business-use portion, and GST handling.
### Parameters
| Parameter | Type | Required | Description |
| ----------------------- | ------- | -------- | ---------------------------------------------------------- |
| `transactionId` | string | Yes | Transaction to update |
| `categoryId` | string | No | Category ID |
| `categoryName` | string | No | Category name (looked up if ID is missing) |
| `isTaxDeductible` | boolean | No | Mark as deductible |
| `businessUsePercentage` | number | No | Business use (0-100) |
| `gstIncluded` | boolean | No | Whether GST/VAT is included in the amount |
| `gstAmount` | number | No | GST/VAT amount; calculated and recorded for you if omitted |
If you don't pass `gstAmount`, it's calculated and recorded for you based on the transaction.
### Example Response
```json theme={null}
{
"success": true,
"data": {
"transactionId": "txn_123",
"category": "Office Expenses",
"isTaxDeductible": true,
"businessUsePercentage": 80,
"message": "✅ Updated transaction..."
}
}
```
***
## get\_spending\_outlook
Hybrid Analytics Tool
Combines settled transactions and future bill occurrences to answer “What will I spend in the next X days?”
### Parameters
| Parameter | Type | Required | Description |
| ---------------------- | ------- | -------- | ------------------------------------------------- |
| `startDate` | string | No | Defaults to today |
| `endDate` | string | No | Defaults to +60 days |
| `includeActual` | boolean | No | Include processed transactions (default: true) |
| `includeProjected` | boolean | No | Include bill projections (default: true) |
| `includeOverdue` | boolean | No | Include overdue occurrences (default: true) |
| `includePaidProjected` | boolean | No | Include already-paid occurrences (default: false) |
| `limit` | number | No | Max records per section (default: 250, max 500) |
### Example Response (trimmed)
```json theme={null}
{
"success": true,
"data": {
"window": { "startDate": "2025-11-01", "endDate": "2026-01-01", "days": 62 },
"totals": { "actual": 2450.15, "projected": 3120.00, "combined": 5570.15 },
"actual": { "count": 42, "records": [...] },
"projected": { "count": 18, "overdueCount": 2, "records": [...] }
}
}
```
***
## Real-World Examples
### Get Recent Expenses
**User**: "Show my expenses from last month"
**AI calls**:
```json theme={null}
{
"tool": "get_transactions",
"params": {
"startDate": "2025-02-01",
"endDate": "2025-02-28",
"primaryType": "expense"
}
}
```
### Tax Deductible Summary
**User**: "How much can I deduct this quarter?"
**AI calls**:
```json theme={null}
{
"tool": "get_tax_deductible_summary",
"params": {
"startDate": "2025-01-01",
"endDate": "2025-03-31"
}
}
```
**AI responds**: "You have 156 tax deductible transactions totaling $24,532.75 this quarter. Breakdown by category: Office Expenses ($3,250.50), Travel ($12,500.00), Professional Services ($8,782.25)."
### Add Transaction
**User**: "Create a transaction for lunch \$45 today"
**AI calls**:
```json theme={null}
{
"tool": "create_transaction",
"params": {
"description": "Lunch",
"amount": -45.00,
"date": "2025-10-30",
"primaryType": "expense",
"secondaryType": "one-time expense"
}
}
```
### Categorize Uncategorized
**User**: "Categorize my uncategorized transactions"
**AI calls**:
```json theme={null}
{
"tool": "trigger_smart_categorization",
"params": {}
}
```
### Analytics - Category Breakdown
**User**: "What's my biggest expense category this month?"
**AI calls**:
```json theme={null}
{
"tool": "get_category_spending_summary",
"params": {
"startDate": "2024-10-01",
"endDate": "2024-10-31"
}
}
```
**AI responds**: "Your biggest expense category in October was Groceries at $1,245.67 (32% of spending), followed by Dining Out at $876.43 (23%)."
### Analytics - Top Merchants
**User**: "Where do I spend the most?"
**AI calls**:
```json theme={null}
{
"tool": "get_top_merchants",
"params": {
"startDate": "2024-10-01",
"endDate": "2024-10-31",
"limit": 5
}
}
```
### Analytics - Period Comparison
**User**: "Did I spend more this month vs last month?"
**AI calls**:
```json theme={null}
{
"tool": "compare_spending_periods",
"params": {
"period1Start": "2024-10-01",
"period1End": "2024-10-31",
"period2Start": "2024-09-01",
"period2End": "2024-09-30",
"groupBy": "total"
}
}
```
**AI responds**: "You spent $3,876.42 in October compared to $3,234.21 in September - an increase of \$642.21 (19.9%)."
### Bulk Operations - Categorize by Merchant
**User**: "Categorize all Uber transactions as Transport"
**AI calls**:
```json theme={null}
{
"tool": "bulk_categorize_transactions",
"params": {
"filterByMerchant": "Uber",
"categoryId": "cat_transport_123"
}
}
```
### Bulk Operations - Find Duplicates
**User**: "Did I pay this bill twice?"
**AI calls**:
```json theme={null}
{
"tool": "find_duplicate_transactions",
"params": {
"startDate": "2024-10-01",
"endDate": "2024-10-31"
}
}
```
### Explain a Categorization
**AI calls**:
```json theme={null}
{
"tool": "analyze_transaction_categorization",
"params": {
"transactionId": "txn_123"
}
}
```
### Apply the Suggestion
**AI calls**:
```json theme={null}
{
"tool": "apply_analysis_to_transaction",
"params": {
"transactionId": "txn_123",
"categoryId": "cat_office",
"isTaxDeductible": true,
"businessUsePercentage": 80
}
}
```
### Forecast the Next 60 Days
**AI calls**:
```json theme={null}
{
"tool": "get_spending_outlook",
"params": {
"startDate": "2025-11-01",
"endDate": "2026-01-01"
}
}
```
***
## Important Notes
### Transaction Amounts
* **Negative** = Expenses (e.g., -100 means you spent \$100)
* **Positive** = Income (e.g., +100 means you received \$100)
### Primary Types
* `expense` - Money going out
* `income` - Money coming in
* `transfer` - Moving money between accounts
### Secondary Types (for expenses)
* `bill` - Recurring bills
* `one-time expense` - One-off purchases
* `capital expense` - Large asset purchases
### Fast, ready-to-use results
* Tax and categorisation results come back already calculated — there's no waiting for re-analysis when you read your data.
* Use `trigger_smart_categorization` when you want AI2Fin to (re)categorise transactions.
### Privacy and speed
* Queries are fast and scoped to your account, so your assistant gets answers quickly.
* You only ever see your own data — every request is tied to your credentials.
***
## Next Steps
Manage recurring bills
Check feature access