> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veroreceipts.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool reference

> Complete reference for all tools available on the Vero MCP Server

The Vero MCP Server exposes tools organized into 5 categories:

* [**User context**](#user-context) — Identity and integration status
* [**Bank accounts**](#bank-accounts) — Connect, list, and disconnect bank accounts
* [**Transactions**](#transactions) — Search and filter transactions with itemized receipt data
* [**Receipts**](#receipts) — Upload, match, and manage receipts
* [**Email**](#email) — Connect Gmail and scan for receipts

All tools require authentication — the user must complete the OAuth flow before any tool can be called.

***

## User context

### get\_user\_context

Returns a consolidated snapshot of the user's identity and current integration state, including bank connection status, email connection status, and profile info.

**Parameters:** None

**Use this tool** to understand what the user has set up before suggesting actions. This is typically the first tool called in a conversation.

<Accordion title="Example response">
  ```json theme={null}
  {
    "user": {
      "sub": "auth0|abc123",
      "email": "user@example.com",
      "name": "Jane Doe"
    },
    "status": {
      "has_bank_account": true,
      "accounts_count": 2
    },
    "email": {
      "connected": true,
      "provider": "google"
    }
  }
  ```
</Accordion>

***

## Bank accounts

### connect\_bank\_account

Creates a Plaid Link session and returns a URL for the user to connect their bank account in a browser. After the user completes the flow, the account is automatically linked.

**Parameters:** None

<Info>
  This tool returns a browser URL. The user must open the link and complete the Plaid Link flow. The AI assistant cannot complete this step on the user's behalf.
</Info>

***

### get\_accounts

Returns the user's connected bank accounts with balances and account details.

**Parameters:** None

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "account_id": "abc123",
      "name": "Checking Account",
      "type": "depository",
      "subtype": "checking",
      "balance": {
        "available": 1250.00,
        "current": 1300.00,
        "currency": "USD"
      },
      "institution": "Chase"
    }
  ]
  ```
</Accordion>

***

### disconnect\_bank\_account

Disconnects a bank account. This removes the entire institution connection, so all accounts under the same institution will be disconnected.

**Parameters:**

<ParamField body="account_id" type="string" required>
  The account ID to disconnect. Use `get_accounts` to find it.
</ParamField>

<Warning>
  This disconnects all accounts under the same institution, not just the specified account. Only call this once per institution.
</Warning>

***

## Transactions

### get\_transactions

Syncs the latest transactions from Plaid and returns them. Supports extensive filtering and sorting.

**Parameters:**

<ParamField body="search" type="string">
  Search transactions by name or merchant name.
</ParamField>

<ParamField body="date_from" type="string">
  Start date filter. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="date_to" type="string">
  End date filter. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="amount_min" type="string">
  Minimum transaction amount (absolute value).
</ParamField>

<ParamField body="amount_max" type="string">
  Maximum transaction amount (absolute value).
</ParamField>

<ParamField body="category" type="string">
  Filter by transaction category. One of:

  `BANK_FEES` `ENTERTAINMENT` `FOOD_AND_DRINK` `GENERAL_MERCHANDISE` `GENERAL_SERVICES` `GOVERNMENT_AND_NON_PROFIT` `HOME_IMPROVEMENT` `INCOME` `LOAN_DISBURSEMENTS` `LOAN_PAYMENTS` `MEDICAL` `OTHER` `PERSONAL_CARE` `RENT_AND_UTILITIES` `TRANSFER_IN` `TRANSFER_OUT` `TRANSPORTATION` `TRAVEL`
</ParamField>

<ParamField body="matched" type="string">
  Filter by receipt match status. One of: `matched`, `unmatched`.
</ParamField>

<ParamField body="pending" type="string">
  Filter by pending status. One of: `true`, `false`.
</ParamField>

<ParamField body="sort_by" type="string">
  Sort field. One of: `date`, `amount`, `merchant`, `name`. Default: `date`.
</ParamField>

<ParamField body="sort_order" type="string">
  Sort direction. One of: `asc`, `desc`. Default: `desc`.
</ParamField>

<Accordion title="Example response">
  ```json theme={null}
  [
    {
      "transaction_id": "txn_abc123",
      "name": "STARBUCKS #1234",
      "merchant_name": "Starbucks",
      "amount": 5.75,
      "date": "2026-04-10",
      "category": "FOOD_AND_DRINK",
      "pending": false,
      "matched": true,
      "receipt_id": "rec_xyz789"
    }
  ]
  ```
</Accordion>

***

## Receipts

### ingest\_receipt\_image

Creates a receipt upload session and returns a URL for the user to upload a receipt image in their browser. The uploaded image is processed with OCR and automatically matched to transactions when possible.

**Parameters:** None

<Info>
  After showing the upload URL to the user, immediately call `wait_for_receipt_upload` with the returned `session_id` to get the OCR and matching results.
</Info>

***

### wait\_for\_receipt\_upload

Waits for a receipt image upload to complete. Call this after `ingest_receipt_image` once the user has been given the upload URL. Blocks until the user uploads the image or the session times out.

**Parameters:**

<ParamField body="session_id" type="string" required>
  The session ID returned by `ingest_receipt_image`.
</ParamField>

<Note>
  This tool blocks for up to 5 minutes waiting for the user to upload. If the session times out, it returns an error.
</Note>

***

### get\_receipts

Returns the user's receipts with optional filters. Includes match status, OCR-extracted data, and linked transaction info.

**Parameters:**

<ParamField body="status" type="string">
  Filter by receipt status. One of: `matched`, `unmatched`, `suggested`.
</ParamField>

<ParamField body="source" type="string">
  Filter by receipt source. One of: `upload`, `email`.
</ParamField>

<ParamField body="match_method" type="string">
  Filter by how the receipt was matched. One of: `auto`, `manual`, `suggested`, `confirmed`.
</ParamField>

<ParamField body="search" type="string">
  Search by merchant name or line items.
</ParamField>

<ParamField body="date_from" type="string">
  Start date filter. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="date_to" type="string">
  End date filter. Format: `YYYY-MM-DD`.
</ParamField>

<ParamField body="amount_min" type="string">
  Minimum receipt amount.
</ParamField>

<ParamField body="amount_max" type="string">
  Maximum receipt amount.
</ParamField>

<ParamField body="sort_by" type="string">
  Sort field. One of: `date`, `amount`, `merchant`. Default: `created_at`.
</ParamField>

<ParamField body="sort_order" type="string">
  Sort direction. One of: `asc`, `desc`. Default: `desc`.
</ParamField>

***

### match\_receipt

Manually matches a receipt to a specific transaction. Use when automatic matching didn't find the right transaction or when the user wants to link a specific receipt to a specific transaction.

**Parameters:**

<ParamField body="receipt_id" type="string" required>
  The UUID of the receipt to match.
</ParamField>

<ParamField body="transaction_id" type="string" required>
  The Plaid transaction ID to match the receipt to.
</ParamField>

***

### unmatch\_receipt

Removes an existing association between a receipt and a transaction.

**Parameters:**

<ParamField body="receipt_id" type="string" required>
  The UUID of the receipt to unmatch.
</ParamField>

***

### confirm\_receipt\_suggestion

Confirms an auto-suggested receipt-to-transaction match. Use when the system suggested a match and the user agrees it's correct.

**Parameters:**

<ParamField body="receipt_id" type="string" required>
  The UUID of the receipt whose suggestion to confirm.
</ParamField>

***

### reject\_receipt\_suggestion

Rejects an auto-suggested receipt-to-transaction match. Use when the system suggested a match but the user says it's wrong.

**Parameters:**

<ParamField body="receipt_id" type="string" required>
  The UUID of the receipt whose suggestion to reject.
</ParamField>

***

## Email

### connect\_email

Initiates Gmail connection via Google OAuth. Returns a URL for the user to authorize Gmail access in a browser. Once connected, Vero can scan the inbox for receipts.

**Parameters:** None

<Info>
  The user must open the returned URL and complete the Google OAuth flow. Only Gmail is currently supported.
</Info>

***

### scan\_email

Scans the user's connected Gmail inbox for receipts. Runs in the background — results may take a moment to appear.

**Parameters:** None

<Note>
  The user must have a connected email account before calling this tool. Use `get_user_context` to check.
</Note>

***

### list\_email\_receipts

Returns receipts that were discovered from scanning the user's email inbox.

**Parameters:** None

***

## Tool summary

| Tool                         | Category     | Parameters                     | Description                                  |
| ---------------------------- | ------------ | ------------------------------ | -------------------------------------------- |
| `get_user_context`           | User         | None                           | Get user identity and connection status      |
| `connect_bank_account`       | Bank         | None                           | Get Plaid Link URL to connect a bank account |
| `get_accounts`               | Bank         | None                           | List connected accounts with balances        |
| `disconnect_bank_account`    | Bank         | `account_id`                   | Disconnect an institution                    |
| `get_transactions`           | Transactions | 10 optional filters            | Search and filter transactions               |
| `ingest_receipt_image`       | Receipts     | None                           | Get URL for receipt image upload             |
| `wait_for_receipt_upload`    | Receipts     | `session_id`                   | Wait for upload to complete                  |
| `get_receipts`               | Receipts     | 10 optional filters            | List and filter receipts                     |
| `match_receipt`              | Receipts     | `receipt_id`, `transaction_id` | Manually match receipt to transaction        |
| `unmatch_receipt`            | Receipts     | `receipt_id`                   | Remove receipt-transaction match             |
| `confirm_receipt_suggestion` | Receipts     | `receipt_id`                   | Confirm auto-suggested match                 |
| `reject_receipt_suggestion`  | Receipts     | `receipt_id`                   | Reject auto-suggested match                  |
| `connect_email`              | Email        | None                           | Get Google OAuth URL for Gmail               |
| `scan_email`                 | Email        | None                           | Scan inbox for receipts                      |
| `list_email_receipts`        | Email        | None                           | List email-sourced receipts                  |