> ## 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.

# MCP tools reference — parameters and responses

> Complete parameter and response reference for AI2Fin MCP tools: transactions, bills, custom rules, travel, receipts, tax analysis, and more.

## 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](/mcp/tools-overview). To get connected, start with the [Quickstart](/mcp/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` <Badge text="NEW" />

Parameters: `{ startDate, endDate, minAmount?, limit? }`

Returns: `{ success, data: { totalSpending, totalTransactions, categories[], topCategory } }`

`get_top_merchants` <Badge text="NEW" />

Parameters: `{ startDate, endDate, limit? }`

Returns: `{ success, data: { totalSpending, merchants[] } }`

`compare_spending_periods` <Badge text="NEW" />

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` <Badge text="NEW" />

Parameters: `{ transactionIds[]?, categoryId, filterByMerchant?, filterStartDate?, filterEndDate? }`

Returns: `{ success, data: { updatedCount, categoryName, message } }`

`bulk_update_transactions` <Badge text="NEW" />

Parameters: `{ transactionIds[], updates: { categoryId?, isTaxDeductible?, businessUsePercentage?, notes? } }`

Returns: `{ success, data: { updatedCount, fields[], message } }`

`find_duplicate_transactions` <Badge text="NEW" />

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**:
  ```json theme={null}
  {
    "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**:
  ```json theme={null}
  {
    "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**:
  ```json theme={null}
  {
    "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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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:

```json theme={null}
{ "id": "string", "tripDate": "ISO?", "tripType": "?", "purpose": "?", "startOdometer": "?", "endOdometer": "?", "startLocation": "?", "endLocation": "?", "isReturnJourney": "?", "notes": "?" }
```

`get_travel_deduction_summary`

Parameters:

```json theme={null}
{ "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` <Badge text="NEW" />

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

Returns: `{ success, data, rulesApplied, message }`

`update_bill_pattern` <Badge text="NEW" />

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` <Badge text="NEW" />

Parameters: `{ isPaid?, startDate?, endDate?, merchantName?, billPatternId?, limit? }`

Returns: `{ success, data: { occurrences[], count, totalAmount, filters } }`

`get_overdue_bills` <Badge text="NEW" />

Parameters: `{ limit? }`

Returns: `{ success, data: { occurrences[], count, totalOverdue } }`

`get_bill_pattern_financial_summary` <Badge text="NEW" />

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` <Badge text="NEW" />

Parameters: `{ occurrenceId, paidDate?, actualAmount?, transactionId?, notes? }`

Returns: `{ success, data: { occurrence, message } }`

`upload_receipt_for_bill` <Badge text="NEW" />

Parameters: `{ occurrenceId, receiptUrl, receiptFileName?, notes? }`

Returns: `{ success, data: { occurrence, message } }`

## Custom Rules

`get_rules`

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

`create_rule`

Parameters:

```json theme={null}
{
  "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):

```json theme={null}
{
  "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**:
  ```json theme={null}
  {
    "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) <Badge text="Coming Soon" variant="warning" />

`create_budget`, `get_budgets`, `get_budget_status`, `update_budget`, `delete_budget`

These tools are planned and not yet available. Until then, calling one returns:

```json theme={null}
{ "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**   |