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

{
  "startDate": "2025-01-01",
  "endDate": "2025-03-31",
  "isTaxDeductible": true,
  "limit": 50
}

Example Response

{
  "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

{
  "startDate": "2025-01-01",
  "endDate": "2025-12-31"
}

Example Response

{
  "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

{
  "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

{
  "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

{
  "transactionIds": ["clx123abc", "clx456def"],
  "force": false
}

Example Response

{
  "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

{
  "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

{
  "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)

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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)

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "tool": "trigger_smart_categorization",
  "params": {}
}

Analytics - Category Breakdown

User: “What’s my biggest expense category this month?” AI calls:

{
  "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:

{
  "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:

{
  "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:

{
  "tool": "bulk_categorize_transactions",
  "params": {
    "filterByMerchant": "Uber",
    "categoryId": "cat_transport_123"
  }
}

Bulk Operations - Find Duplicates

User: “Did I pay this bill twice?” AI calls:

{
  "tool": "find_duplicate_transactions",
  "params": {
    "startDate": "2024-10-01",
    "endDate": "2024-10-31"
  }
}

Explain a Categorization

AI calls:

{
  "tool": "analyze_transaction_categorization",
  "params": {
    "transactionId": "txn_123"
  }
}

Apply the Suggestion

AI calls:

{
  "tool": "apply_analysis_to_transaction",
  "params": {
    "transactionId": "txn_123",
    "categoryId": "cat_office",
    "isTaxDeductible": true,
    "businessUsePercentage": 80
  }
}

Forecast the Next 60 Days

AI calls:

{
  "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.

​Transaction Tools

​get_transactions

​Parameters

​Response fields

​Example Request

​Example Response

​get_tax_deductible_summary

​Parameters

​Example Request

​Example Response

​create_transaction

​Parameters

​Example Request

​Example Response

​trigger_smart_categorization

​Parameters

​Example Request

​Example Response

​get_category_spending_summary

​Parameters

​Example Response

​get_top_merchants

​Parameters

​Example Response

​compare_spending_periods

​Parameters

​Example Response (Total Comparison)

​bulk_categorize_transactions

​Parameters

​Example Response

​bulk_update_transactions

​Parameters

​Example Response

​find_duplicate_transactions

​Parameters

​Example Response

​analyze_transaction_categorization

​Parameters

​Example Response

​analyze_transaction_tax_deductibility

​Parameters

​Example Response

​apply_analysis_to_transaction

​Parameters

​Example Response

​get_spending_outlook

​Parameters

​Example Response (trimmed)

​Real-World Examples

​Get Recent Expenses

​Tax Deductible Summary

​Add Transaction

​Categorize Uncategorized

​Analytics - Category Breakdown

​Analytics - Top Merchants

​Analytics - Period Comparison

​Bulk Operations - Categorize by Merchant

​Bulk Operations - Find Duplicates

​Explain a Categorization

​Apply the Suggestion

​Forecast the Next 60 Days

​Important Notes

​Transaction Amounts

​Primary Types

​Secondary Types (for expenses)

​Fast, ready-to-use results

​Privacy and speed

​Next Steps

Bill Tools

Subscription Tools

Transaction Tools

get_transactions

Parameters

Response fields

Example Request

Example Response

get_tax_deductible_summary

Parameters

Example Request

Example Response

create_transaction

Parameters

Example Request

Example Response

trigger_smart_categorization

Parameters

Example Request

Example Response

get_category_spending_summary

Parameters

Example Response

get_top_merchants

Parameters

Example Response

compare_spending_periods

Parameters

Example Response (Total Comparison)

bulk_categorize_transactions

Parameters

Example Response

bulk_update_transactions

Parameters

Example Response

find_duplicate_transactions

Parameters

Example Response

analyze_transaction_categorization

Parameters

Example Response

analyze_transaction_tax_deductibility

Parameters

Example Response

apply_analysis_to_transaction

Parameters

Example Response

get_spending_outlook

Parameters

Example Response (trimmed)

Real-World Examples

Get Recent Expenses

Tax Deductible Summary

Add Transaction

Categorize Uncategorized

Analytics - Category Breakdown

Analytics - Top Merchants

Analytics - Period Comparison

Bulk Operations - Categorize by Merchant

Bulk Operations - Find Duplicates

Explain a Categorization

Apply the Suggestion

Forecast the Next 60 Days

Important Notes

Transaction Amounts

Primary Types

Secondary Types (for expenses)

Fast, ready-to-use results

Privacy and speed

Next Steps