MCP tools reference — parameters and responses

Overview

This page is the detailed reference for the financial tools your AI assistant can call through the AI2Fin MCP server. For a high-level catalog grouped by category, see the Tools Overview. To get connected, start with the Quickstart. Each tool below lists its parameters and the shape of the response it returns.

Execution & Safety

Every tool requires authentication and is scoped to your account only.
Read operations return data instantly. Write operations (create, update, delete) return a confirmation step first, so nothing changes until you approve it.

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)

These tools provide category recommendations, tax-deductibility checks, and a helper to apply the results you accept.

`analyze_transaction_categorization`

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

Returns:

{
  "success": true,
  "data": {
    "transactionId": "txn_123",
    "analysis": {
      "suggestedCategory": "Office Expenses",
      "reasoning": "Matches your previous office-supply purchases",
      "alternativeCategories": ["Supplies", "Stationery"]
    },
    "message": "Suggested category: Office Expenses..."
  }
}

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,
      "businessUse": "80%",
      "taxCategory": "Office Expenses",
      "documentationRequired": ["Receipt", "Business purpose"],
      "warnings": [],
      "suggestions": ["Capture business mileage if applicable"]
    },
    "message": "Tax analysis: this expense looks tax deductible..."
  }
}

When to use: “Is this deductible?”, “What documentation do I need?” The result includes a GST/VAT breakdown based on your region and preferences—calculated and filled in for you.

`apply_analysis_to_transaction`

Parameters: { transactionId, categoryId?, categoryName?, isTaxDeductible?, businessUsePercentage?, gstIncluded?, gstAmount? } — pass the values you accepted from the analysis to save them on the transaction.

Returns:

{
  "success": true,
  "data": {
    "transactionId": "txn_123",
    "category": "Office Expenses",
    "isTaxDeductible": true,
    "businessUse": "80%",
    "message": "✅ Transaction updated"
  }
}

When to use: After reviewing the analysis, save the approved category and tax details in one call. GST is calculated and filled in for you.

User Profile & Preferences

get_user_profile Parameters: {} Returns:

{
  "success": true,
  "data": {
    "userId": "...",
    "email": "...",
    "countryCode": "AU",
    "businessType": "INDIVIDUAL",
    "industry": null,
    "profession": null,
    "currency": "AUD",
    "aiContext": "Notes you've shared to personalize guidance"
  }
}

set_user_preferences Parameters (any subset):

{
  "countryCode": "ISO",
  "businessType": "string",
  "industry": "string",
  "profession": "string",
  "aiContext": "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 }
Returns: { success, data: { extracted, candidates[], asset } }
Usage: Run after uploading a receipt to read the merchant, totals, and GST, and to find the likely matching transaction. Your assistant uses this before suggesting a commit.

commit_receipt

Parameters: { assetUrl, mimeType, size, 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 These tools are planned and not yet available. Until then, calling one returns:

{ "success": false, "error": "coming_soon", "data": { "message": "Budgets coming soon!" } }

Want budget recommendations today? Use suggest_budgets for AI-generated budget ideas based on your spending.

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

​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