create_transaction

Creates a bookkeeping transaction record in Savi for the authenticated user. It does not move money, initiate a bank transfer, or place a trade.

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: Creates data
  • Required scope: write (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": "create_transaction",
    "arguments": {
      "name": "Emergency fund"
    }
  }
}

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

Description

Creates a bookkeeping transaction record in Savi for the authenticated user. It does not move money, initiate a bank transfer, or place a trade.

For precision-aware transactions, provide exactAmount with signed string units and decimal scale; specify currency when needed. Transfers can include toAccountId and toExactAmount.

Required fields: name and either amount or exactAmount.
category, accountId, and transactedAt can be omitted for intent-first MCP usage defaults.

⚠️  GOLDEN RULE — NEVER infer, guess, default, or invent ANY required field.
Every required field must come DIRECTLY from what the user said. If the user did not
clearly provide a field, STOP and ask them for it — do not proceed with a substitute.
MCP intent defaults:
  • If category is omitted, infer it from the transaction name and amount (e.g. "wireless headphones" => GENERAL_MERCHANDISE).
  • If transactedAt is omitted, default to today (RFC 3339).
  • If accountId is omitted, default to the account named "Main Checking" when available.
    If "Main Checking" is not available: use the only accessible account when exactly one exists.
    If still ambiguous, ask the user to choose an account.

Edge-case parsing rule for purchases:
  • If the user gives a TOTAL amount plus an item/service (e.g. "spent $300 on headphones" or "bought $300 headphones"),
    treat both as the same intent: a single purchase with that item name and amount -30000 (cents).
  • If quantity is NOT explicitly stated, assume default quantity = 1.
  • Do NOT split total into unit price × quantity unless the user explicitly gives quantity or per-item pricing.

Natural-language name is OK (e.g. name="Log $5 coffee") — amount/name/category are inferred.
A trailing "on <account>" in the name (e.g. "Log $5 coffee on checking") selects that account when it matches one.
Optional accountName resolves the account without an ID; an unknown or ambiguous accountName asks which account.
If an identical name+amount exists on the same account within 24 hours, this asks before doubling up unless confirmDuplicate=true.

Examples of what is NOT allowed:
  • User says "add a coffee transaction" (no amount) → DO NOT guess an amount. Ask: "How much was it?"
  • User says "Log $4.50" (no description) → DO NOT invent a name. Ask: "What was it for?"
  • User says "my account" with multiple accounts → DO NOT pick the default. Call list_accounts and ask which one.

Per-field rules:
  • accountId: the account the USER explicitly chose. Vague reference + multiple accounts → ask.
  • name: a specific label the user gave (e.g. "Coffee", "Rent"). Never a placeholder like "Transaction".
  • amount: the exact amount the user stated, in cents ($4.50 → -450 for an expense). Never 0 and never a guess.
  • category: inferred when omitted; informal names (e.g. "food", "groceries") auto-map to the closest system category (FOOD_AND_DRINK).
  • transactedAt: the date the user gave, as RFC 3339. "today" is fine to resolve to today's date.

RESOLVING MISSING CONTEXT — call the appropriate tool before retrying:
  • accountId unknown → call list_accounts; use account.id.
  • category unclear  → call list_categories; use category.name (only if inference is not suitable).
  • tagIds unknown    → call list_tags; use tag.id values.

Amounts are in cents. Sign convention: negative for expenses, positive for income.
type (INCOME, EXPENSE, TRANSFER) is optional and inferred from amount/category when omitted.
fileIds defaults to [] when omitted.

Input parameters

NameTypeRequiredDescription
accountIdstringNo
accountNamestringNo
amountnumberNo
appleCardTransactionobjectNo
categorystringNo
categoryIdstringNo
clientRequestIdstringNo
confirmDuplicatebooleanNo
cronExpressionstringNo
currencystringNo
descriptionstringNo
endDatestringNo
exactAmountobjectNo
expenseCategorystringNo
fileIdsarrayNo
incomeCategorystringNo
isExcludedFromAnalyticsbooleanNo
lineItemsarrayNo
namestringYes
subcategorystringNo
tagIdsarrayNo
tagNamesarrayNo
toAccountIdstringNo
toExactAmountobjectNo
transactedAtstringNo
typestringNo
vendorIdstringNo
vendorNamestringNo
Full input schema (JSON Schema)
json
{
  "additionalProperties": false,
  "properties": {
    "accountId": {
      "type": [
        "null",
        "string"
      ]
    },
    "accountName": {
      "type": [
        "null",
        "string"
      ]
    },
    "amount": {
      "type": [
        "null",
        "number"
      ]
    },
    "appleCardTransaction": {
      "additionalProperties": false,
      "properties": {
        "transactionId": {
          "type": "string"
        }
      },
      "required": [
        "transactionId"
      ],
      "type": [
        "null",
        "object"
      ]
    },
    "category": {
      "type": [
        "null",
        "string"
      ]
    },
    "categoryId": {
      "type": [
        "null",
        "string"
      ]
    },
    "clientRequestId": {
      "type": [
        "null",
        "string"
      ]
    },
    "confirmDuplicate": {
      "type": [
        "null",
        "boolean"
      ]
    },
    "cronExpression": {
      "type": [
        "null",
        "string"
      ]
    },
    "currency": {
      "type": [
        "null",
        "string"
      ]
    },
    "description": {
      "type": [
        "null",
        "string"
      ]
    },
    "endDate": {
      "type": [
        "null",
        "string"
      ]
    },
    "exactAmount": {
      "additionalProperties": false,
      "properties": {
        "scale": {
          "description": "Decimal scale from 0 through 18",
          "maximum": 255,
          "minimum": 0,
          "type": "integer"
        },
        "units": {
          "description": "Signed integer units encoded as a decimal string",
          "type": "string"
        }
      },
      "required": [
        "units",
        "scale"
      ],
      "type": [
        "null",
        "object"
      ]
    },
    "expenseCategory": {
      "type": [
        "null",
        "string"
      ]
    },
    "fileIds": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "incomeCategory": {
      "type": [
        "null",
        "string"
      ]
    },
    "isExcludedFromAnalytics": {
      "type": [
        "null",
        "boolean"
      ]
    },
    "lineItems": {
      "items": {
        "additionalProperties": false,
        "properties": {
          "amount": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "amount"
        ],
        "type": "object"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "name": {
      "type": "string"
    },
    "subcategory": {
      "type": [
        "null",
        "string"
      ]
    },
    "tagIds": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "tagNames": {
      "items": {
        "type": "string"
      },
      "type": [
        "null",
        "array"
      ]
    },
    "toAccountId": {
      "type": [
        "null",
        "string"
      ]
    },
    "toExactAmount": {
      "additionalProperties": false,
      "properties": {
        "scale": {
          "description": "Decimal scale from 0 through 18",
          "maximum": 255,
          "minimum": 0,
          "type": "integer"
        },
        "units": {
          "description": "Signed integer units encoded as a decimal string",
          "type": "string"
        }
      },
      "required": [
        "units",
        "scale"
      ],
      "type": [
        "null",
        "object"
      ]
    },
    "transactedAt": {
      "type": [
        "null",
        "string"
      ]
    },
    "type": {
      "type": [
        "null",
        "string"
      ]
    },
    "vendorId": {
      "type": [
        "null",
        "string"
      ]
    },
    "vendorName": {
      "type": [
        "null",
        "string"
      ]
    }
  },
  "required": [
    "name"
  ],
  "type": "object"
}