MCP Tools (AI Assistant Internal APIs)

Overview

These tools are invoked by the assistant server-side under the authenticated user. They never require client tokens and respect row-level isolation by userId.

Execution & Safety

All tools require auth (handled by the server). Results are scoped to the current user.
The assistant performs a silent intent check and prefers tools first; it only asks the user for missing fields if a lookup fails.

Transactions (10 tools)

Query & Analysis

get_transactions Parameters: { startDate?, endDate?, merchant?, q?, isTaxDeductible?, categoryId?, minAmount?, maxAmount?, amountEquals?, limit? } Returns: { success, data: { transactions, count, filters } } get_tax_deductible_summary Parameters: { startDate?, endDate? } Returns: { success, data: { totalCount, totalAmount, byCategory, dateRange } } get_category_spending_summary Parameters: { startDate, endDate, minAmount?, limit? } Returns: { success, data: { totalSpending, totalTransactions, categories[], topCategory } } get_top_merchants Parameters: { startDate, endDate, limit? } Returns: { success, data: { totalSpending, merchants[] } } compare_spending_periods Parameters: { period1Start, period1End, period2Start, period2End, groupBy? } Returns: { success, data: { period1, period2, difference, percentChange, trend, comparison[] } }

Creation & Categorization

create_transaction Parameters: { description, amount, date, type, merchant?, categoryId?, isTaxDeductible?, notes? } Returns: { success, data: { transaction }, rulesApplied, message } trigger_smart_categorization Parameters: { transactionIds[] } Returns: { success, data: { queued, message } }

Bulk Operations

bulk_categorize_transactions Parameters: { transactionIds[]?, categoryId, filterByMerchant?, filterStartDate?, filterEndDate? } Returns: { success, data: { updatedCount, categoryName, message } } bulk_update_transactions Parameters: { transactionIds[], updates: { categoryId?, isTaxDeductible?, businessUsePercentage?, notes? } } Returns: { success, data: { updatedCount, fields[], message } } find_duplicate_transactions Parameters: { startDate, endDate, toleranceHours?, amountTolerance? } Returns: { success, data: { duplicateGroupsCount, duplicateGroups[], potentialSavings } }

AI Analysis Tools (3)

AI2Fin’s assistant mirrors the production AI services. These tools deliver categorization recommendations, tax deductions, and a helper to persist approved results.

`analyze_transaction_categorization`

Parameters: { transactionId, merchant?, description?, amount? }

Returns:

{
  "success": true,
  "data": {
    "transactionId": "txn_123",
    "analysis": {
      "suggestedCategory": "Office Expenses",
      "confidence": 0.92,
      "reasoning": "Matches previous office supply purchases",
      "alternativeCategories": ["Supplies", "Stationery"]
    },
    "message": "AI suggests Office Expenses (92% confidence)..."
  }
}

When to use: “How should I categorize this transaction?”, “Explain why you picked that category.”

`analyze_transaction_tax_deductibility`

Parameters: { transactionId }

Returns:

{
  "success": true,
  "data": {
    "analysis": {
      "isTaxDeductible": true,
      "businessUsePercentage": 80,
      "taxCategory": "Office Expenses",
      "documentationRequired": ["Receipt", "Business purpose"],
      "warnings": [],
      "suggestions": ["Capture business mileage if applicable"]
    },
    "message": "Tax Analysis: ✓ Tax Deductible (95% confidence)..."
  }
}

When to use: “Is this deductible?”, “What documentation do I need for GST?” Results include GST/VAT breakdown consistent with user preferences.

`apply_analysis_to_transaction`

Parameters: { transactionId, categoryId?, categoryName?, isTaxDeductible?, businessUsePercentage?, gstIncluded?, gstAmount? }

Returns:

{
  "success": true,
  "data": {
    "transactionId": "txn_123",
    "category": "Office Expenses",
    "isTaxDeductible": true,
    "businessUsePercentage": 80,
    "gstAmount": 10.0,
    "message": "✅ Updated transaction..."
  }
}

When to use: After presenting AI results, apply the approved category/tax/GST updates in one call.

User Profile & Preferences

get_user_profile Parameters: {} Returns:

{
  "success": true,
  "data": {
    "userId": "...",
    "email": "...",
    "countryCode": "AU",
    "businessType": "INDIVIDUAL",
    "industry": null,
    "profession": null,
    "currency": "AUD",
    "aiContextInput": "...",
    "psychologyVersion": 1
  }
}

set_user_preferences Parameters (any subset):

{
  "countryCode": "ISO",
  "businessType": "string",
  "industry": "string",
  "profession": "string",
  "aiContextInput": "string"
}

Returns: { success, data: { userId, updated: [fields...] } }

Travel (Vehicles & Trips)

get_travel_profile Parameters: {} Returns: { success, data: { countryCode, currency, defaultMethod } } get_vehicles Parameters: {} Returns: vehicle list for the user. get_trips Parameters:

{
  "from": "ISO optional",
  "to": "ISO optional",
  "vehicleId": "string optional",
  "tripType": "BUSINESS|EMPLOYEE optional",
  "limit": 200
}

Returns: trips for the user. create_trip Parameters (required unless marked optional):

{
  "vehicleId": "string",
  "tripDate": "ISO",
  "tripType": "BUSINESS|EMPLOYEE",
  "purpose": "string",
  "startOdometer": 0,
  "endOdometer": 0,
  "startLocation": "string optional",
  "endLocation": "string optional",
  "isReturnJourney": false,
  "notes": "string optional"
}

update_trip Parameters:

{ "id": "string", "tripDate": "ISO?", "tripType": "?", "purpose": "?", "startOdometer": "?", "endOdometer": "?", "startLocation": "?", "endLocation": "?", "isReturnJourney": "?", "notes": "?" }

get_travel_deduction_summary Parameters:

{ "year": 2025 }

Returns: { success, data: { countryCode, period: { from, to }, totalKm, byVehicle } }

Subscription

get_user_subscription, check_feature_access – used to tailor features/guidance to plan.

Bills (10 tools)

Bill Patterns

get_bills Parameters: { active? } Returns: { success, data: { bills[], count } } get_bill_summary Parameters: {} Returns: { success, data: { totalBills, monthlyTotal, byFrequency, bills[] } } create_bill_pattern Parameters:

{ merchantName, amount, firstDueDate, frequency, description?, categoryId?, isTaxDeductible?, businessUsePercentage?, notes? }

Returns: { success, data, rulesApplied, message } update_bill_pattern Parameters: { billPatternId, merchantName?, amount?, frequency?, categoryId?, isTaxDeductible?, isActive? } Returns: { success, data, message }

Bill Occurrences

get_upcoming_bills Parameters: { days?, includeOverdue? } Returns: { success, data: { occurrences[], count, daysAhead } } get_bill_occurrences Parameters: { isPaid?, startDate?, endDate?, merchantName?, billPatternId?, limit? } Returns: { success, data: { occurrences[], count, totalAmount, filters } } get_overdue_bills Parameters: { limit? } Returns: { success, data: { occurrences[], count, totalOverdue } } get_bill_pattern_financial_summary Parameters: { billPatternId?/merchantName?, period, startDate?, endDate?, includeProjections? } Period options: financial_year, year_to_date, calendar_year, all_time, custom Returns: { success, data: { billPattern, period, actualPaid, projected, summary } }

Payment Management

mark_bill_as_paid Parameters: { occurrenceId, paidDate?, actualAmount?, transactionId?, notes? } Returns: { success, data: { occurrence, message } } upload_receipt_for_bill Parameters: { occurrenceId, receiptUrl, receiptFileName?, notes? } Returns: { success, data: { occurrence, message } }

Custom Rules

get_rules Parameters: { "isActive?": boolean, "name?": string, "limit?": number } create_rule Parameters:

{
  "name": "string",
  "description": "string?",
  "isActive": true,
  "priority": 0,
  "conditionLogic": "AND|OR",
  "targetEntityType": "transaction|bill_pattern|bill_occurrence|all",
  "conditions": {},
  "actions": {}
}

update_rule Parameters: { "id": "string", ...any of the create fields } delete_rule Parameters: { "id": "string" } enable_rule Parameters: { "id": "string", "isActive": true } test_rule Parameters (limited evaluator for transactions):

{
  "conditions": {
    "merchantContains": "string?",
    "descriptionContains": "string?",
    "amountGte": 0,
    "amountLte": 999,
    "categoryId": "string?"
  },
  "sampleLimit": 200
}

Returns: { success, data: { tested, matchedCount, sampleIds } }

Receipt Tools (2)

analyze_receipt

Parameters: { assetUrl, mimeType, size, sha256? }
Returns: { success, data: { extracted, candidates[], asset } }
Usage: Run after uploading a receipt to extract merchant, totals, GST, and potential matching transactions. The assistant uses this before suggesting a commit.

commit_receipt

Parameters: { assetUrl, mimeType, size, sha256?, extracted?, action: { type: "link" | "create_expense", transactionId?, updateFields? } }
Returns: { success, data: { entityType, entityId } }
Usage: Link the analyzed receipt to an existing transaction (type link) or create a new expense (create_expense). Include updateFields to adjust merchant/date/amount during linking.

Spending Outlook (1 tool)

get_spending_outlook

Parameters: { startDate?, endDate?, includeActual?, includeProjected?, includeOverdue?, includePaidProjected?, limit? }

Returns:

{
  "success": true,
  "data": {
    "window": { "startDate": "...", "endDate": "...", "days": 60 },
    "totals": { "actual": 2450.15, "projected": 3120.00, "combined": 5570.15 },
    "actual": { "count": 42, "total": 2450.15, "records": [...] },
    "projected": { "count": 18, "total": 3120.00, "overdueCount": 2, "records": [...] }
  }
}

Usage: Answer “What will I owe in the next 60 days?” by blending settled expenses with upcoming bill occurrences while avoiding double counting linked transactions.

Budgets (5 tools)

create_budget, get_budgets, get_budget_status, update_budget, delete_budget Currently return: { success: false, error: "coming_soon", data: { message: "Budgets coming soon!" } } Framework ready for Phase 2 implementation.

Tool Count Summary

Category	Tools	Status
Transactions	10	✅ Live
Bills	10	✅ Live
Custom Rules	6	✅ Live
Travel	5	✅ Live
User Profile	2	✅ Live
Subscription	2	✅ Live
Expenses	1	✅ Live
Receipts	2	✅ Live
AI Analysis	3	✅ Live
Spending Outlook	1	✅ Live
Budgets	5	⏳ Coming Soon
TOTAL	47	42 Live

Getting Started

Authentication

Tools Reference

Integration

MCP Tools (AI Assistant Internal APIs)

Overview

Execution & Safety

Transactions (10 tools)

Query & Analysis

Creation & Categorization

Bulk Operations

AI Analysis Tools (3)

`analyze_transaction_categorization`

`analyze_transaction_tax_deductibility`

`apply_analysis_to_transaction`

User Profile & Preferences

Travel (Vehicles & Trips)

Subscription

Bills (10 tools)

Bill Patterns

Bill Occurrences

Payment Management

Custom Rules

Receipt Tools (2)

Spending Outlook (1 tool)

Budgets (5 tools)

Tool Count Summary

Getting Started

Authentication

Tools Reference

Integration

​Overview

​Execution & Safety

​Transactions (10 tools)

​Query & Analysis

​Creation & Categorization

​Bulk Operations

​AI Analysis Tools (3)

​analyze_transaction_categorization

​analyze_transaction_tax_deductibility

​apply_analysis_to_transaction

​User Profile & Preferences

​Travel (Vehicles & Trips)

​Subscription

​Bills (10 tools)

​Bill Patterns

​Bill Occurrences

​Payment Management

​Custom Rules

​Receipt Tools (2)

​Spending Outlook (1 tool)

​Budgets (5 tools)

​Tool Count Summary

Overview

Execution & Safety

Transactions (10 tools)

Query & Analysis

Creation & Categorization

Bulk Operations

AI Analysis Tools (3)

`analyze_transaction_categorization`

`analyze_transaction_tax_deductibility`

`apply_analysis_to_transaction`

User Profile & Preferences

Travel (Vehicles & Trips)

Subscription

Bills (10 tools)

Bill Patterns

Bill Occurrences

Payment Management

Custom Rules

Receipt Tools (2)

Spending Outlook (1 tool)

Budgets (5 tools)

Tool Count Summary