list_transactions

Lists transactions for the authenticated user with optional filters. Call this to: • Show recent transaction history to the user. • Search for a specific trans…

Use with an AI agent

Export this page as Markdown or bundle it with a task for your agent.

Try a task
Preview the prompt that will be copied

Access

  • Effect: Read-only
  • Required scope: read (the mcp scope also grants it)

Example request

The JSON-RPC message an MCP client sends to call this tool. Your client builds it for you; this is for reference and debugging in a tool such as MCP Inspector.

json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_transactions",
    "arguments": {}
  }
}

Example IDs refer to fictional demo data. Replace them with IDs from your account before calling the real server.

Description

Lists transactions for the authenticated user with optional filters. Call this to:
  • Show recent transaction history to the user.
  • Search for a specific transaction before deciding to add a new one (avoid duplicates).
  • Resolve "latest/last transaction" requests before read/delete actions.
  • Answer "what do I categorize Uber as?" via vendorHint / categoryHint.

Filter IDs (accountIds, tagIds, categoryIds) come from list_accounts, list_tags, and list_categories respectively.
categories accepts human names (e.g. "general merchandise", "food") — auto-mapped to system enums. Combine with transactionType INCOME or EXPENSE.
vendorHint / categoryHint are informal shortcuts (e.g. vendorHint="Uber", categoryHint="food").
Dates must be RFC 3339 strings (e.g. "2025-01-01T00:00:00Z"). transactionType: INCOME, EXPENSE, or TRANSFER.
Temporal relativity tip: map natural language ranges (today, yesterday, this week, last month) to startDate/endDate in RFC 3339 before calling.
Set includeExactAmount when precision matters. When exactAmount is present, interpret its string units at the given decimal scale instead of rounding the legacy amount.

Defaults: most recent transactions across all accounts; pass limit to cap result size.

Input parameters

NameTypeRequiredDescription
accountIdsarrayNo
categoriesarrayNo
categoryHintstringNo
categoryIdsarrayNo
endDatestringNo
includeExactAmountbooleanNo
limitintegerNo
maxAmountInclusivenumberNo
minAmountInclusivenumberNo
searchQuerystringNo
skipintegerNo
startDatestringNo
tagIdsarrayNo
transactionTypestringNo
vendorHintstringNo
vendorNamesarrayNo
Full input schema (JSON Schema)
json
{
  "additionalProperties": false,
  "properties": {
    "accountIds": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "categories": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "categoryHint": {
      "type": [
        "null",
        "string"
      ]
    },
    "categoryIds": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "endDate": {
      "type": [
        "null",
        "string"
      ]
    },
    "includeExactAmount": {
      "type": "boolean"
    },
    "limit": {
      "type": [
        "null",
        "integer"
      ]
    },
    "maxAmountInclusive": {
      "type": [
        "null",
        "number"
      ]
    },
    "minAmountInclusive": {
      "type": [
        "null",
        "number"
      ]
    },
    "searchQuery": {
      "type": [
        "null",
        "string"
      ]
    },
    "skip": {
      "type": [
        "null",
        "integer"
      ]
    },
    "startDate": {
      "type": [
        "null",
        "string"
      ]
    },
    "tagIds": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "transactionType": {
      "type": [
        "null",
        "string"
      ]
    },
    "vendorHint": {
      "type": [
        "null",
        "string"
      ]
    },
    "vendorNames": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    }
  },
  "type": "object"
}