Transaction Tools

AI2Fin MCP provides 10 tools for transaction management, analytics, and bulk operations with direct database access for maximum performance.

All transaction data is user-isolated. You can only access your own transactions.

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)

Real Transaction Fields

{
  id: string;
  transactionId: string;         // Unique transaction ID
  userId: string;                // Owner
  description: string;           // Transaction description
  amount: number;                // Amount (negative = expense, positive = income)
  date: string;                  // ISO date
  
  // Primary categorization
  primaryType: string;           // "expense" | "income" | "transfer"
  secondaryType?: string;        // "bill" | "one-time expense" | "capital expense"
  
  // Tax & business
  isTaxDeductible: boolean;
  taxDeductionReason?: string;
  businessUsePercentage: number; // 0-100
  
  // Categorization
  category?: {
    id: string;
    name: string;
    color: string;
  };
  categoryId?: string;
  
  // Recurrence
  recurring: boolean;
  recurrencePattern?: string;    // "weekly" | "monthly" | "quarterly" | "adhoc"
  nextDueDate?: string;
  
  // Metadata
  merchant?: string;
  reference?: string;
  notes?: string;
  receiptUrl?: string;
  
  // AI analysis (cached)
  aiTaxAnalysis?: string;        // JSON string of AI analysis
  taxCache?: string;             // Cached tax analysis
  
  // Rules
  appliedRuleId?: string;
  appliedRuleName?: string;
  ruleAppliedAt?: string;
  
  // Status
  processed: boolean;
  needsReview: boolean;
}

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",
        "aiTaxAnalysis": "{\"deductible\":true,\"reason\":\"Office supplies for business use\",\"confidence\":0.95}",
        "recurring": false,
        "processed": true,
        "needsReview": 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

Triggers AI categorization on uncategorized or specified transactions.

This runs the actual AI categorization flow - it does NOT re-analyze. It uses the existing cached AI analysis or triggers new analysis if not present.

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

Detects potential duplicate payments based on merchant, amount, and date proximity.

Parameters

Parameter	Type	Required	Description
`startDate`	string	Yes	Start date to search
`endDate`	string	Yes	End date to search
`toleranceHours`	number	No	Time window (default: 72 hours)
`amountTolerance`	number	No	Amount tolerance (default: $0.01)

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

Uses the intelligent categorization service to suggest the best category for a transaction with confidence and reasoning.

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

Runs the Intelligent Tax Deduction Service to determine tax deductibility, business use percentage, documentation requirements, and 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 AI recommendations to the transaction: category, tax flags, business use percentage, and GST metadata.

Parameters

Parameter	Type	Required	Description
`transactionId`	string	Yes	Transaction to update
`categoryId`	string	No	Category ID
`categoryName`	string	No	Category name (lookup if ID missing)
`isTaxDeductible`	boolean	No	Mark as deductible
`businessUsePercentage`	number	No	Business use (0-100)
`gstIncluded`	boolean	No	Whether GST is included
`gstAmount`	number	No	GST amount

Example Response

{
  "success": true,
  "data": {
    "transactionId": "txn_123",
    "category": "Office Expenses",
    "isTaxDeductible": true,
    "businessUsePercentage": 80,
    "gstAmount": 10,
    "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,
    "gstAmount": 10
  }
}

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

AI Analysis Caching

aiTaxAnalysis field contains cached AI analysis
NO re-analysis on retrieval (fast!)
Use trigger_smart_categorization to update if needed

Performance

Direct database access = ~5-10ms response time
No HTTP overhead
User-isolated queries (secure)

Next Steps

Bill Tools

Manage recurring bills

Subscription Tools

Check feature access

Getting Started

Authentication

Tools Reference

Integration

​Transaction Tools

​get_transactions

​Parameters

​Real Transaction 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)

​AI Analysis Caching

​Performance

​Next Steps

Bill Tools

Subscription Tools

Transaction Tools

get_transactions

Parameters

Real Transaction 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)

AI Analysis Caching

Performance

Next Steps