@dizzlkheinz/ynab-mcpb 0.18.4 → 0.19.0

package/src/tools/transactionWriteTools.ts

@@ -0,0 +1,2110 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type * as ynab from "ynab";
+import type { SaveSubTransaction } from "ynab/dist/models/SaveSubTransaction.js";
+import type { SaveTransaction } from "ynab/dist/models/SaveTransaction.js";
+import type { z } from "zod/v4";
+import { CacheManager, cacheManager } from "../server/cacheManager.js";
+import type { DeltaCache } from "../server/deltaCache.js";
+import type { ErrorHandler } from "../server/errorHandler.js";
+import { globalRequestLogger } from "../server/requestLogger.js";
+import { responseFormatter } from "../server/responseFormatter.js";
+import type { ServerKnowledgeStore } from "../server/serverKnowledgeStore.js";
+import type { ToolRegistry } from "../server/toolRegistry.js";
+import { ValidationError, withToolErrorHandling } from "../types/index.js";
+import type { ToolContext } from "../types/toolRegistration.js";
+import {
+	amountToMilliunits,
+	milliunitsToAmount,
+} from "../utils/amountUtils.js";
+import { createAdapters, createBudgetResolver } from "./adapters.js";
+import { resolveDeltaWriteArgs } from "./deltaSupport.js";
+import { ToolAnnotationPresets } from "./toolCategories.js";
+
+import {
+	type BulkCreateResponse,
+	type BulkUpdateResponse,
+	type BulkUpdateResult,
+	type BulkUpdateTransactionInput,
+	type CreateReceiptSplitTransactionParams,
+	CreateReceiptSplitTransactionSchema,
+	type CreateTransactionParams,
+	CreateTransactionSchema,
+	type CreateTransactionsParams,
+	CreateTransactionsSchema,
+	type DeleteTransactionParams,
+	DeleteTransactionSchema,
+	type ReceiptCategoryCalculation,
+	type SubtransactionInput,
+	type UpdateTransactionParams,
+	UpdateTransactionSchema,
+	type UpdateTransactionsParams,
+	UpdateTransactionsSchema,
+} from "./transactionSchemas.js";
+
+import {
+	appendCategoryIds,
+	collectCategoryIdsFromSources,
+	correlateResults,
+	ensureTransaction,
+	finalizeBulkUpdateResponse,
+	finalizeResponse,
+	handleTransactionError,
+	invalidateTransactionCaches,
+	setsEqual,
+	toMonthKey,
+} from "./transactionUtils.js";
+
+/**
+ * Handles the ynab:create_transaction tool call
+ * Creates a new transaction in the specified budget and account
+ */
+export async function handleCreateTransaction(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: CreateTransactionParams,
+): Promise<CallToolResult>;
+export async function handleCreateTransaction(
+	ynabAPI: ynab.API,
+	params: CreateTransactionParams,
+): Promise<CallToolResult>;
+export async function handleCreateTransaction(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | CreateTransactionParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionParams,
+	maybeParams?: CreateTransactionParams,
+	_errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	try {
+		if (params.dry_run) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							dry_run: true,
+							action: "create_transaction",
+							request: params,
+						}),
+					},
+				],
+			};
+		}
+		// Prepare transaction data
+		const transactionData: SaveTransaction = {
+			account_id: params.account_id,
+			amount: params.amount, // Already validated as integer milliunits
+			date: params.date,
+			cleared: params.cleared as ynab.TransactionClearedStatus,
+			flag_color: params.flag_color as ynab.TransactionFlagColor,
+		};
+		if (params.payee_name !== undefined)
+			transactionData.payee_name = params.payee_name;
+		if (params.payee_id !== undefined)
+			transactionData.payee_id = params.payee_id;
+		if (params.category_id !== undefined)
+			transactionData.category_id = params.category_id;
+		if (params.memo !== undefined) transactionData.memo = params.memo;
+		if (params.approved !== undefined)
+			transactionData.approved = params.approved;
+		if (params.import_id !== undefined)
+			transactionData.import_id = params.import_id;
+		if (params.subtransactions && params.subtransactions.length > 0) {
+			const subtransactions: SaveSubTransaction[] = params.subtransactions.map(
+				(subtransaction) => {
+					const mapped: SaveSubTransaction = {
+						amount: subtransaction.amount,
+					};
+
+					if (subtransaction.payee_name !== undefined)
+						mapped.payee_name = subtransaction.payee_name;
+					if (subtransaction.payee_id !== undefined)
+						mapped.payee_id = subtransaction.payee_id;
+					if (subtransaction.category_id !== undefined) {
+						mapped.category_id = subtransaction.category_id;
+					}
+					if (subtransaction.memo !== undefined)
+						mapped.memo = subtransaction.memo;
+
+					return mapped;
+				},
+			);
+
+			transactionData.subtransactions = subtransactions;
+		}
+
+		const response = await ynabAPI.transactions.createTransaction(
+			params.budget_id,
+			{
+				transaction: transactionData,
+			},
+		);
+
+		const transaction = ensureTransaction(
+			response.data.transaction,
+			"Transaction creation failed",
+		);
+
+		const affectedAccountIds = new Set<string>([transaction.account_id]);
+		const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
+		const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
+		invalidateTransactionCaches(
+			deltaCache,
+			knowledgeStore,
+			params.budget_id,
+			response.data.server_knowledge,
+			affectedAccountIds,
+			affectedMonths,
+			{
+				affectedCategoryIds,
+				accountTotalsChanged: true,
+				invalidateMonths: true,
+			},
+		);
+
+		// Get the updated account balance
+		const accountResponse = await ynabAPI.accounts.getAccountById(
+			params.budget_id,
+			transaction.account_id,
+		);
+		const account = accountResponse.data.account;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: responseFormatter.format({
+						transaction: {
+							id: transaction.id,
+							date: transaction.date,
+							amount: milliunitsToAmount(transaction.amount),
+							memo: transaction.memo,
+							cleared: transaction.cleared,
+							approved: transaction.approved,
+							flag_color: transaction.flag_color,
+							account_id: transaction.account_id,
+							payee_id: transaction.payee_id,
+							category_id: transaction.category_id,
+							transfer_account_id: transaction.transfer_account_id,
+							transfer_transaction_id: transaction.transfer_transaction_id,
+							matched_transaction_id: transaction.matched_transaction_id,
+							import_id: transaction.import_id,
+							deleted: transaction.deleted,
+							// New fields for account balance
+							account_balance: account.balance,
+							account_cleared_balance: account.cleared_balance,
+							subtransactions: transaction.subtransactions?.map(
+								(subtransaction) => ({
+									id: subtransaction.id,
+									transaction_id: subtransaction.transaction_id,
+									amount: milliunitsToAmount(subtransaction.amount),
+									memo: subtransaction.memo,
+									payee_id: subtransaction.payee_id,
+									payee_name: subtransaction.payee_name,
+									category_id: subtransaction.category_id,
+									category_name: subtransaction.category_name,
+									transfer_account_id: subtransaction.transfer_account_id,
+									transfer_transaction_id:
+										subtransaction.transfer_transaction_id,
+									deleted: subtransaction.deleted,
+								}),
+							),
+						},
+					}),
+				},
+			],
+		};
+	} catch (error) {
+		return handleTransactionError(error, "Failed to create transaction");
+	}
+}
+
+/**
+ * Constants for smart collapse logic
+ */
+const BIG_TICKET_THRESHOLD_MILLIUNITS = 50000; // $50.00
+const COLLAPSE_THRESHOLD = 5; // Collapse if 5 or more remaining items
+const MAX_ITEMS_PER_MEMO = 5;
+const MAX_MEMO_LENGTH = 150;
+
+/**
+ * Truncates a string to fit within maxLength, adding ellipsis if truncated
+ */
+function truncateToLength(str: string, maxLength: number): string {
+	if (str.length <= maxLength) {
+		return str;
+	}
+	const ellipsis = "...";
+	return str.substring(0, maxLength - ellipsis.length) + ellipsis;
+}
+
+function buildItemMemo(item: {
+	name: string;
+	quantity: number | undefined;
+	memo: string | undefined;
+}): string | undefined {
+	const quantitySuffix = item.quantity ? ` (x${item.quantity})` : "";
+	let result: string;
+	if (item.memo && item.memo.trim().length > 0) {
+		result = `${item.name}${quantitySuffix} - ${item.memo}`;
+	} else if (quantitySuffix) {
+		result = `${item.name}${quantitySuffix}`;
+	} else {
+		result = item.name;
+	}
+	// Truncate to MAX_MEMO_LENGTH if needed
+	return truncateToLength(result, MAX_MEMO_LENGTH);
+}
+
+/**
+ * Applies smart collapse logic to receipt items according to the specification:
+ * 1. Extract special items (big ticket, returns, discounts)
+ * 2. Apply threshold to remaining items
+ * 3. Collapse by category if needed
+ * 4. Handle tax allocation
+ */
+function applySmartCollapseLogic(
+	categoryCalculations: ReceiptCategoryCalculation[],
+	taxMilliunits: number,
+): SubtransactionInput[] {
+	// Step 1: Extract special items and classify remaining items
+	interface SpecialItem {
+		item: ReceiptCategoryCalculation["items"][0];
+		category_id: string;
+		category_name: string | undefined;
+	}
+
+	interface CategoryItems {
+		category_id: string;
+		category_name: string | undefined;
+		items: ReceiptCategoryCalculation["items"][0][];
+	}
+
+	const specialItems: SpecialItem[] = [];
+	const remainingItemsByCategory: CategoryItems[] = [];
+
+	for (const category of categoryCalculations) {
+		const categorySpecials: ReceiptCategoryCalculation["items"][0][] = [];
+		const categoryRemaining: ReceiptCategoryCalculation["items"][0][] = [];
+
+		for (const item of category.items) {
+			const isNegative = item.amount_milliunits < 0;
+			const unitPrice = item.quantity
+				? item.amount_milliunits / item.quantity
+				: item.amount_milliunits;
+			const isBigTicket = unitPrice > BIG_TICKET_THRESHOLD_MILLIUNITS;
+
+			if (isNegative || isBigTicket) {
+				categorySpecials.push(item);
+			} else {
+				categoryRemaining.push(item);
+			}
+		}
+
+		// Add specials to the special items list (preserving category order)
+		for (const item of categorySpecials) {
+			specialItems.push({
+				item,
+				category_id: category.category_id,
+				category_name: category.category_name,
+			});
+		}
+
+		// Track remaining items by category
+		if (categoryRemaining.length > 0) {
+			remainingItemsByCategory.push({
+				category_id: category.category_id,
+				category_name: category.category_name,
+				items: categoryRemaining,
+			});
+		}
+	}
+
+	// Step 2: Count total remaining positive items
+	const totalRemainingItems = remainingItemsByCategory.reduce(
+		(sum, cat) => sum + cat.items.length,
+		0,
+	);
+
+	// Step 3: Decide whether to collapse
+	const shouldCollapse = totalRemainingItems >= COLLAPSE_THRESHOLD;
+
+	// Build subtransactions
+	const subtransactions: SubtransactionInput[] = [];
+
+	// Add special items first (returns, discounts, big tickets)
+	for (const special of specialItems) {
+		const memo = buildItemMemo({
+			name: special.item.name,
+			quantity: special.item.quantity,
+			memo: special.item.memo,
+		});
+		const payload: SubtransactionInput = {
+			amount: -special.item.amount_milliunits,
+			category_id: special.category_id,
+		};
+		if (memo) payload.memo = memo;
+		subtransactions.push(payload);
+	}
+
+	// Add remaining items (collapsed or itemized)
+	if (shouldCollapse) {
+		// Collapse by category
+		for (const categoryGroup of remainingItemsByCategory) {
+			const collapsedSubtransactions = collapseItemsByCategory(categoryGroup);
+			subtransactions.push(...collapsedSubtransactions);
+		}
+	} else {
+		// Itemize each remaining item individually
+		for (const categoryGroup of remainingItemsByCategory) {
+			for (const item of categoryGroup.items) {
+				const memo = buildItemMemo({
+					name: item.name,
+					quantity: item.quantity,
+					memo: item.memo,
+				});
+				const payload: SubtransactionInput = {
+					amount: -item.amount_milliunits,
+					category_id: categoryGroup.category_id,
+				};
+				if (memo) payload.memo = memo;
+				subtransactions.push(payload);
+			}
+		}
+	}
+
+	// Step 4: Handle tax allocation
+	const taxSubtransactions = allocateTax(categoryCalculations, taxMilliunits);
+	subtransactions.push(...taxSubtransactions);
+
+	return subtransactions;
+}
+
+/**
+ * Collapses items within a category into groups of up to MAX_ITEMS_PER_MEMO
+ */
+function collapseItemsByCategory(categoryGroup: {
+	category_id: string;
+	category_name: string | undefined;
+	items: ReceiptCategoryCalculation["items"][0][];
+}): SubtransactionInput[] {
+	const subtransactions: SubtransactionInput[] = [];
+	const items = categoryGroup.items;
+
+	let currentBatch: ReceiptCategoryCalculation["items"][0][] = [];
+	let currentBatchTotal = 0;
+
+	for (const item of items) {
+		// Check if we've hit the max items per memo
+		if (currentBatch.length >= MAX_ITEMS_PER_MEMO) {
+			// Flush current batch
+			const memo = buildCollapsedMemo(currentBatch);
+			subtransactions.push({
+				amount: -currentBatchTotal,
+				category_id: categoryGroup.category_id,
+				memo,
+			});
+			currentBatch = [];
+			currentBatchTotal = 0;
+		}
+
+		// Try adding this item to the current batch
+		const testBatch = [...currentBatch, item];
+		const testMemo = buildCollapsedMemo(testBatch);
+
+		if (testMemo.length <= MAX_MEMO_LENGTH) {
+			// Fits - add to batch
+			currentBatch.push(item);
+			currentBatchTotal += item.amount_milliunits;
+		} else {
+			// Doesn't fit - flush current batch and start new one
+			if (currentBatch.length > 0) {
+				const memo = buildCollapsedMemo(currentBatch);
+				subtransactions.push({
+					amount: -currentBatchTotal,
+					category_id: categoryGroup.category_id,
+					memo,
+				});
+				currentBatch = [item];
+				currentBatchTotal = item.amount_milliunits;
+			} else {
+				// Edge case: single item is too long, use it anyway
+				currentBatch = [item];
+				currentBatchTotal = item.amount_milliunits;
+			}
+		}
+	}
+
+	// Flush remaining batch
+	if (currentBatch.length > 0) {
+		const memo = buildCollapsedMemo(currentBatch);
+		subtransactions.push({
+			amount: -currentBatchTotal,
+			category_id: categoryGroup.category_id,
+			memo,
+		});
+	}
+
+	return subtransactions;
+}
+
+/**
+ * Truncates an item name to fit within available space
+ * Preserves the amount suffix and adds "..." to indicate truncation
+ */
+function truncateItemName(
+	name: string,
+	amountSuffix: string,
+	maxLength: number,
+): string {
+	const ellipsis = "...";
+	// We need: truncatedName + ellipsis + amountSuffix <= maxLength
+	const availableForName = maxLength - ellipsis.length - amountSuffix.length;
+
+	if (availableForName <= 0) {
+		// Edge case: amount suffix alone is too long, just return what we can
+		return amountSuffix.substring(0, maxLength);
+	}
+
+	return name.substring(0, availableForName) + ellipsis + amountSuffix;
+}
+
+/**
+ * Builds a collapsed memo from a list of items
+ * Format: "Item1 $X.XX, Item2 $Y.YY, Item3 $Z.ZZ"
+ * Truncates with "..." if needed (either individual items or the list)
+ */
+function buildCollapsedMemo(
+	items: ReceiptCategoryCalculation["items"][0][],
+): string {
+	const parts: string[] = [];
+	let currentLength = 0;
+
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (!item) continue;
+		const amount = milliunitsToAmount(item.amount_milliunits);
+		const amountSuffix = ` $${amount.toFixed(2)}`;
+		let itemStr = `${item.name}${amountSuffix}`;
+		const separator = i > 0 ? ", " : "";
+
+		// For the first item, check if it alone exceeds the limit
+		if (parts.length === 0 && itemStr.length > MAX_MEMO_LENGTH) {
+			itemStr = truncateItemName(item.name, amountSuffix, MAX_MEMO_LENGTH);
+		}
+
+		const testLength = currentLength + separator.length + itemStr.length;
+
+		// Check if adding this item would exceed limit
+		if (parts.length > 0 && testLength + 4 > MAX_MEMO_LENGTH) {
+			// Would exceed - stop here and add "..."
+			break;
+		}
+
+		parts.push(itemStr);
+		currentLength = testLength;
+	}
+
+	let result = parts.join(", ");
+
+	// Add "..." if we didn't include all items
+	if (parts.length < items.length) {
+		result += "...";
+	}
+
+	return result;
+}
+
+/**
+ * Allocates tax across categories
+ * - Positive categories get proportional tax subtransactions
+ * - Negative tax creates a single tax refund subtransaction
+ */
+function allocateTax(
+	categoryCalculations: ReceiptCategoryCalculation[],
+	taxMilliunits: number,
+): SubtransactionInput[] {
+	const subtransactions: SubtransactionInput[] = [];
+
+	// Handle tax = 0
+	if (taxMilliunits === 0) {
+		return subtransactions;
+	}
+
+	// Handle negative tax (refund)
+	if (taxMilliunits < 0) {
+		// Find category with largest return
+		let largestReturnCategory: ReceiptCategoryCalculation | undefined =
+			undefined;
+		let largestReturnAmount = 0;
+
+		for (const category of categoryCalculations) {
+			const categoryReturnAmount = category.items
+				.filter((item) => item.amount_milliunits < 0)
+				.reduce((sum, item) => sum + Math.abs(item.amount_milliunits), 0);
+
+			if (categoryReturnAmount > largestReturnAmount) {
+				largestReturnAmount = categoryReturnAmount;
+				largestReturnCategory = category;
+			}
+		}
+
+		// Default to first category if no returns found
+		if (!largestReturnCategory) {
+			largestReturnCategory = categoryCalculations[0];
+		}
+
+		if (largestReturnCategory) {
+			subtransactions.push({
+				amount: -taxMilliunits,
+				category_id: largestReturnCategory.category_id,
+				memo: "Tax refund",
+			});
+		}
+
+		return subtransactions;
+	}
+
+	// Positive tax - allocate proportionally to positive categories only
+	const positiveCategorySubtotals = categoryCalculations
+		.map((cat) => ({
+			category: cat,
+			positiveSubtotal: cat.items
+				.filter((item) => item.amount_milliunits > 0)
+				.reduce((sum, item) => sum + item.amount_milliunits, 0),
+		}))
+		.filter((x) => x.positiveSubtotal > 0);
+
+	if (positiveCategorySubtotals.length === 0) {
+		// No positive items, no tax allocation
+		return subtransactions;
+	}
+
+	const totalPositiveSubtotal = positiveCategorySubtotals.reduce(
+		(sum, x) => sum + x.positiveSubtotal,
+		0,
+	);
+
+	// Distribute tax using largest remainder method
+	let allocatedTax = 0;
+	const taxAllocations: {
+		category: ReceiptCategoryCalculation;
+		taxAmount: number;
+	}[] = [];
+
+	for (let i = 0; i < positiveCategorySubtotals.length; i++) {
+		const entry = positiveCategorySubtotals[i];
+		if (!entry) continue;
+
+		const { category, positiveSubtotal } = entry;
+
+		if (i === positiveCategorySubtotals.length - 1) {
+			// Last category gets remainder
+			const taxAmount = taxMilliunits - allocatedTax;
+			if (taxAmount > 0) {
+				taxAllocations.push({ category, taxAmount });
+			}
+		} else {
+			const taxAmount = Math.round(
+				(taxMilliunits * positiveSubtotal) / totalPositiveSubtotal,
+			);
+			if (taxAmount > 0) {
+				taxAllocations.push({ category, taxAmount });
+				allocatedTax += taxAmount;
+			}
+		}
+	}
+
+	// Create tax subtransactions
+	for (const { category, taxAmount } of taxAllocations) {
+		subtransactions.push({
+			amount: -taxAmount,
+			category_id: category.category_id,
+			memo: `Tax - ${category.category_name ?? "Uncategorized"}`,
+		});
+	}
+
+	return subtransactions;
+}
+
+export async function handleCreateReceiptSplitTransaction(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: CreateReceiptSplitTransactionParams,
+): Promise<CallToolResult>;
+export async function handleCreateReceiptSplitTransaction(
+	ynabAPI: ynab.API,
+	params: CreateReceiptSplitTransactionParams,
+): Promise<CallToolResult>;
+export async function handleCreateReceiptSplitTransaction(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | CreateReceiptSplitTransactionParams,
+	knowledgeStoreOrParams?:
+		| ServerKnowledgeStore
+		| CreateReceiptSplitTransactionParams,
+	maybeParams?: CreateReceiptSplitTransactionParams,
+	_errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	const date = params.date ?? new Date().toISOString().slice(0, 10);
+
+	const categoryCalculations: ReceiptCategoryCalculation[] =
+		params.categories.map((category) => {
+			const items = category.items.map((item) => ({
+				name: item.name,
+				amount_milliunits: amountToMilliunits(item.amount),
+				quantity: item.quantity,
+				memo: item.memo,
+			}));
+			const subtotalMilliunits = items.reduce(
+				(sum, item) => sum + item.amount_milliunits,
+				0,
+			);
+			return {
+				category_id: category.category_id,
+				category_name: category.category_name,
+				subtotal_milliunits: subtotalMilliunits,
+				tax_milliunits: 0,
+				items,
+			};
+		});
+
+	const subtotalMilliunits = categoryCalculations.reduce(
+		(sum, category) => sum + category.subtotal_milliunits,
+		0,
+	);
+
+	const declaredSubtotalMilliunits =
+		params.receipt_subtotal !== undefined
+			? amountToMilliunits(params.receipt_subtotal)
+			: undefined;
+	if (
+		declaredSubtotalMilliunits !== undefined &&
+		Math.abs(declaredSubtotalMilliunits - subtotalMilliunits) > 1
+	) {
+		throw new Error(
+			`Categorized items subtotal (${milliunitsToAmount(subtotalMilliunits)}) does not match receipt subtotal (${milliunitsToAmount(declaredSubtotalMilliunits)})`,
+		);
+	}
+
+	const taxMilliunits = amountToMilliunits(params.receipt_tax);
+	const totalMilliunits = amountToMilliunits(params.receipt_total);
+	const computedTotal = subtotalMilliunits + taxMilliunits;
+	if (Math.abs(computedTotal - totalMilliunits) > 1) {
+		throw new Error(
+			`Receipt total (${milliunitsToAmount(totalMilliunits)}) does not equal subtotal plus tax (${milliunitsToAmount(computedTotal)})`,
+		);
+	}
+
+	// Apply smart collapse logic
+	const subtransactions = applySmartCollapseLogic(
+		categoryCalculations,
+		taxMilliunits,
+	);
+
+	// Distribute tax proportionally for receipt_summary (only for positive categories)
+	if (taxMilliunits > 0) {
+		const positiveSubtotal = categoryCalculations.reduce(
+			(sum, cat) => sum + Math.max(0, cat.subtotal_milliunits),
+			0,
+		);
+		if (positiveSubtotal > 0) {
+			let remainingTax = taxMilliunits;
+			const positiveCats = categoryCalculations.filter(
+				(cat) => cat.subtotal_milliunits > 0,
+			);
+			positiveCats.forEach((cat, index) => {
+				if (index === positiveCats.length - 1) {
+					cat.tax_milliunits = remainingTax;
+				} else {
+					const share = Math.round(
+						(cat.subtotal_milliunits / positiveSubtotal) * taxMilliunits,
+					);
+					cat.tax_milliunits = share;
+					remainingTax -= share;
+				}
+			});
+		}
+	}
+
+	const receiptSummary = {
+		subtotal: milliunitsToAmount(subtotalMilliunits),
+		tax: milliunitsToAmount(taxMilliunits),
+		total: milliunitsToAmount(totalMilliunits),
+		categories: categoryCalculations.map((category) => ({
+			category_id: category.category_id,
+			category_name: category.category_name,
+			items: category.items.map((item) => ({
+				name: item.name,
+				quantity: item.quantity,
+				amount: milliunitsToAmount(item.amount_milliunits),
+				memo: item.memo,
+			})),
+			subtotal: milliunitsToAmount(category.subtotal_milliunits),
+			tax: milliunitsToAmount(category.tax_milliunits),
+			total: milliunitsToAmount(
+				category.subtotal_milliunits + category.tax_milliunits,
+			),
+		})),
+	};
+
+	if (params.dry_run) {
+		return {
+			content: [
+				{
+					type: "text",
+					text: responseFormatter.format({
+						dry_run: true,
+						action: "create_receipt_split_transaction",
+						transaction_preview: {
+							account_id: params.account_id,
+							payee_name: params.payee_name,
+							date,
+							amount: milliunitsToAmount(totalMilliunits),
+							cleared: params.cleared ?? "uncleared",
+						},
+						receipt_summary: receiptSummary,
+						subtransactions: subtransactions.map((subtransaction) => ({
+							amount: milliunitsToAmount(-subtransaction.amount),
+							category_id: subtransaction.category_id,
+							memo: subtransaction.memo,
+						})),
+					}),
+				},
+			],
+		};
+	}
+
+	const createTransactionParams: CreateTransactionParams = {
+		budget_id: params.budget_id,
+		account_id: params.account_id,
+		amount: -totalMilliunits,
+		date,
+		payee_name: params.payee_name,
+		memo: params.memo,
+		cleared: params.cleared ?? "uncleared",
+		flag_color: params.flag_color,
+		subtransactions: subtransactions,
+	};
+
+	if (params.approved !== undefined) {
+		createTransactionParams.approved = params.approved;
+	}
+
+	const baseResult = await handleCreateTransaction(
+		ynabAPI,
+		deltaCache,
+		knowledgeStore,
+		createTransactionParams,
+	);
+
+	const firstContent = baseResult.content?.[0];
+	if (!firstContent || firstContent.type !== "text") {
+		return baseResult;
+	}
+
+	try {
+		const parsed = JSON.parse(firstContent.text) as Record<string, unknown>;
+		parsed["receipt_summary"] = receiptSummary;
+		firstContent.text = responseFormatter.format(parsed);
+	} catch {
+		// If parsing fails, return the original result without augmentation.
+	}
+
+	return baseResult;
+}
+
+/**
+ * Handles the ynab:update_transaction tool call
+ * Updates an existing transaction with the provided fields
+ */
+export async function handleUpdateTransaction(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: UpdateTransactionParams,
+): Promise<CallToolResult>;
+export async function handleUpdateTransaction(
+	ynabAPI: ynab.API,
+	params: UpdateTransactionParams,
+): Promise<CallToolResult>;
+export async function handleUpdateTransaction(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | UpdateTransactionParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionParams,
+	maybeParams?: UpdateTransactionParams,
+	_errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	try {
+		if (params.dry_run) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							dry_run: true,
+							action: "update_transaction",
+							request: params,
+						}),
+					},
+				],
+			};
+		}
+
+		// Get the original transaction before updating to capture the original account_id
+		const originalTransactionResponse =
+			await ynabAPI.transactions.getTransactionById(
+				params.budget_id,
+				params.transaction_id,
+			);
+		const originalTransaction = ensureTransaction(
+			originalTransactionResponse.data.transaction,
+			"Original transaction not found",
+		);
+
+		// Prepare transaction update data - only include fields that are provided
+		const transactionData: SaveTransaction = {};
+
+		// Only include fields that are provided in the update
+		if (params.account_id !== undefined) {
+			transactionData.account_id = params.account_id;
+		}
+		if (params.amount !== undefined) {
+			transactionData.amount = params.amount;
+		}
+		if (params.date !== undefined) {
+			transactionData.date = params.date;
+		}
+		if (params.payee_name !== undefined) {
+			transactionData.payee_name = params.payee_name;
+		}
+		if (params.payee_id !== undefined) {
+			transactionData.payee_id = params.payee_id;
+		}
+		if (params.category_id !== undefined) {
+			transactionData.category_id = params.category_id;
+		}
+		if (params.memo !== undefined) {
+			transactionData.memo = params.memo;
+		}
+		if (params.cleared !== undefined) {
+			transactionData.cleared = params.cleared as ynab.TransactionClearedStatus;
+		}
+		if (params.approved !== undefined) {
+			transactionData.approved = params.approved;
+		}
+		if (params.flag_color !== undefined) {
+			transactionData.flag_color =
+				params.flag_color as ynab.TransactionFlagColor;
+		}
+
+		const response = await ynabAPI.transactions.updateTransaction(
+			params.budget_id,
+			params.transaction_id,
+			{
+				transaction: transactionData,
+			},
+		);
+
+		const transaction = ensureTransaction(
+			response.data.transaction,
+			"Transaction update failed",
+		);
+
+		const specificTransactionCacheKey = CacheManager.generateKey(
+			"transaction",
+			"get",
+			params.budget_id,
+			params.transaction_id,
+		);
+		cacheManager.delete(specificTransactionCacheKey);
+
+		const affectedAccountIds = new Set<string>([
+			originalTransaction.account_id,
+			transaction.account_id,
+		]);
+
+		if (originalTransaction.transfer_account_id) {
+			affectedAccountIds.add(originalTransaction.transfer_account_id);
+		}
+		if (transaction.transfer_account_id) {
+			affectedAccountIds.add(transaction.transfer_account_id);
+		}
+
+		const affectedMonths = new Set<string>([
+			toMonthKey(originalTransaction.date),
+			toMonthKey(transaction.date),
+		]);
+		const originalCategoryIds =
+			collectCategoryIdsFromSources(originalTransaction);
+		const updatedCategoryIds = collectCategoryIdsFromSources(transaction);
+		const affectedCategoryIds = new Set<string>([
+			...originalCategoryIds,
+			...updatedCategoryIds,
+		]);
+		const categoryChanged = !setsEqual(originalCategoryIds, updatedCategoryIds);
+		const amountChanged = transaction.amount !== originalTransaction.amount;
+		const accountChanged =
+			transaction.account_id !== originalTransaction.account_id;
+		const clearedChanged = transaction.cleared !== originalTransaction.cleared;
+		const transferAccountChanged =
+			transaction.transfer_account_id !==
+			originalTransaction.transfer_account_id;
+		const transferLinkChanged =
+			transaction.transfer_transaction_id !==
+			originalTransaction.transfer_transaction_id;
+		const dateChanged = transaction.date !== originalTransaction.date;
+
+		invalidateTransactionCaches(
+			deltaCache,
+			knowledgeStore,
+			params.budget_id,
+			response.data.server_knowledge,
+			affectedAccountIds,
+			affectedMonths,
+			{
+				affectedCategoryIds,
+				accountTotalsChanged:
+					amountChanged ||
+					accountChanged ||
+					clearedChanged ||
+					transferAccountChanged ||
+					transferLinkChanged,
+				invalidateMonths: amountChanged || categoryChanged || dateChanged,
+			},
+		);
+
+		// Get the updated account balance
+		const accountResponse = await ynabAPI.accounts.getAccountById(
+			params.budget_id,
+			transaction.account_id,
+		);
+		const account = accountResponse.data.account;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: responseFormatter.format({
+						transaction: {
+							id: transaction.id,
+							date: transaction.date,
+							amount: milliunitsToAmount(transaction.amount),
+							memo: transaction.memo,
+							cleared: transaction.cleared,
+							approved: transaction.approved,
+							flag_color: transaction.flag_color,
+							account_id: transaction.account_id,
+							payee_id: transaction.payee_id,
+							category_id: transaction.category_id,
+							transfer_account_id: transaction.transfer_account_id,
+							transfer_transaction_id: transaction.transfer_transaction_id,
+							matched_transaction_id: transaction.matched_transaction_id,
+							import_id: transaction.import_id,
+							deleted: transaction.deleted,
+						},
+						updated_balance: account.balance,
+						updated_cleared_balance: account.cleared_balance,
+					}),
+				},
+			],
+		};
+	} catch (error) {
+		return handleTransactionError(error, "Failed to update transaction");
+	}
+}
+
+/**
+ * Handles the ynab:delete_transaction tool call
+ * Deletes a transaction from the specified budget
+ */
+export async function handleDeleteTransaction(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: DeleteTransactionParams,
+): Promise<CallToolResult>;
+export async function handleDeleteTransaction(
+	ynabAPI: ynab.API,
+	params: DeleteTransactionParams,
+): Promise<CallToolResult>;
+export async function handleDeleteTransaction(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | DeleteTransactionParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | DeleteTransactionParams,
+	maybeParams?: DeleteTransactionParams,
+	_errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	try {
+		if (params.dry_run) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format({
+							dry_run: true,
+							action: "delete_transaction",
+							request: params,
+						}),
+					},
+				],
+			};
+		}
+		const response = await ynabAPI.transactions.deleteTransaction(
+			params.budget_id,
+			params.transaction_id,
+		);
+
+		const transaction = ensureTransaction(
+			response.data.transaction,
+			"Transaction deletion failed",
+		);
+
+		const specificTransactionCacheKey = CacheManager.generateKey(
+			"transaction",
+			"get",
+			params.budget_id,
+			params.transaction_id,
+		);
+		cacheManager.delete(specificTransactionCacheKey);
+
+		const affectedAccountIds = new Set<string>([transaction.account_id]);
+		if (transaction.transfer_account_id) {
+			affectedAccountIds.add(transaction.transfer_account_id);
+		}
+
+		const affectedMonths = new Set<string>([toMonthKey(transaction.date)]);
+		const affectedCategoryIds = collectCategoryIdsFromSources(transaction);
+		invalidateTransactionCaches(
+			deltaCache,
+			knowledgeStore,
+			params.budget_id,
+			response.data.server_knowledge,
+			affectedAccountIds,
+			affectedMonths,
+			{
+				affectedCategoryIds,
+				accountTotalsChanged: true,
+				invalidateMonths: true,
+			},
+		);
+
+		// Get the updated account balance
+		const accountResponse = await ynabAPI.accounts.getAccountById(
+			params.budget_id,
+			transaction.account_id,
+		);
+		const account = accountResponse.data.account;
+
+		return {
+			content: [
+				{
+					type: "text",
+					text: responseFormatter.format({
+						message: "Transaction deleted successfully",
+						transaction: {
+							id: transaction.id,
+							deleted: transaction.deleted,
+						},
+						updated_balance: account.balance,
+						updated_cleared_balance: account.cleared_balance,
+					}),
+				},
+			],
+		};
+	} catch (error) {
+		return handleTransactionError(error, "Failed to delete transaction");
+	}
+}
+
+export async function handleCreateTransactions(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: CreateTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleCreateTransactions(
+	ynabAPI: ynab.API,
+	params: CreateTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleCreateTransactions(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | CreateTransactionsParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | CreateTransactionsParams,
+	maybeParams?: CreateTransactionsParams,
+	errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	return (await withToolErrorHandling(
+		async () => {
+			const validationResult = CreateTransactionsSchema.safeParse(params);
+			if (!validationResult.success) {
+				type TransactionIssueIndex = number | null;
+				const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
+				const validationIssues = validationResult.error.issues ?? [];
+				for (const issue of validationIssues) {
+					const transactionIndex = issue.path.find(
+						(segment): segment is number => typeof segment === "number",
+					);
+					const message = issue.message;
+					const issueIndex: TransactionIssueIndex =
+						transactionIndex !== undefined ? transactionIndex : null;
+					const existing = issuesByIndex.get(issueIndex) ?? [];
+					existing.push(message);
+					issuesByIndex.set(issueIndex, existing);
+				}
+
+				const details = Array.from(issuesByIndex.entries()).map(
+					([index, errors]) => ({
+						transaction_index: index,
+						errors,
+					}),
+				);
+
+				throw new ValidationError(
+					"Bulk transaction validation failed",
+					JSON.stringify(details, null, 2),
+					[
+						"Ensure each transaction includes required fields",
+						"Limit batches to 100 items",
+					],
+				);
+			}
+
+			const { budget_id, transactions, dry_run } = validationResult.data;
+
+			// Pre-flight duplicate import_id detection within batch
+			const importIdMap = new Map<string, number[]>();
+			for (const [index, transaction] of transactions.entries()) {
+				if (transaction.import_id && transaction.import_id.trim().length > 0) {
+					const existing = importIdMap.get(transaction.import_id);
+					if (existing) {
+						existing.push(index);
+					} else {
+						importIdMap.set(transaction.import_id, [index]);
+					}
+				}
+			}
+
+			const duplicates = Array.from(importIdMap.entries())
+				.filter(([, indices]) => indices.length > 1)
+				.map(([importId, indices]) => ({ import_id: importId, indices }));
+
+			if (duplicates.length > 0) {
+				const details = duplicates.map(({ import_id, indices }) => ({
+					import_id,
+					transaction_indices: indices,
+					count: indices.length,
+				}));
+
+				throw new ValidationError(
+					"Duplicate import_id values detected within batch",
+					JSON.stringify(details, null, 2),
+					[
+						"Ensure each transaction has a unique import_id within the batch",
+						"Remove duplicate import_id values or omit import_id to use hash-based correlation",
+					],
+				);
+			}
+
+			if (dry_run) {
+				const totalAmount = transactions.reduce(
+					(sum, transaction) => sum + transaction.amount,
+					0,
+				);
+				const accountsAffected = Array.from(
+					new Set(transactions.map((transaction) => transaction.account_id)),
+				);
+				const categoriesAffected = Array.from(
+					new Set(
+						transactions
+							.map((transaction) => transaction.category_id)
+							.filter((id): id is string => id !== undefined),
+					),
+				);
+				const sortedDates = [
+					...transactions.map((transaction) => transaction.date),
+				].sort();
+				const dateRange =
+					sortedDates.length > 0
+						? {
+								earliest: sortedDates[0],
+								latest: sortedDates[sortedDates.length - 1],
+							}
+						: undefined;
+
+				const transactionsPreview = transactions
+					.slice(0, 10)
+					.map((transaction, index) => ({
+						request_index: index,
+						account_id: transaction.account_id,
+						date: transaction.date,
+						amount: milliunitsToAmount(transaction.amount),
+						memo: transaction.memo,
+						payee_id: transaction.payee_id,
+						payee_name: transaction.payee_name,
+						category_id: transaction.category_id,
+						import_id: transaction.import_id,
+					}));
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format({
+								dry_run: true,
+								action: "create_transactions",
+								validation: "passed",
+								summary: {
+									total_transactions: transactions.length,
+									total_amount: milliunitsToAmount(totalAmount),
+									accounts_affected: accountsAffected,
+									date_range: dateRange,
+									categories_affected: categoriesAffected,
+								},
+								transactions_preview: transactionsPreview,
+								note: "Dry run complete. No transactions created. No caches invalidated. No server_knowledge updated.",
+							}),
+						},
+					],
+				};
+			}
+
+			const saveTransactions: SaveTransaction[] = transactions.map(
+				(transaction) => {
+					const payload: SaveTransaction = {
+						account_id: transaction.account_id,
+						amount: transaction.amount,
+						date: transaction.date,
+					};
+
+					if (transaction.payee_id !== undefined)
+						payload.payee_id = transaction.payee_id;
+					if (transaction.payee_name !== undefined)
+						payload.payee_name = transaction.payee_name;
+					if (transaction.category_id !== undefined)
+						payload.category_id = transaction.category_id;
+					if (transaction.memo !== undefined) payload.memo = transaction.memo;
+					if (transaction.cleared !== undefined)
+						payload.cleared = transaction.cleared;
+					if (transaction.approved !== undefined)
+						payload.approved = transaction.approved;
+					if (transaction.flag_color !== undefined)
+						payload.flag_color = transaction.flag_color;
+					if (transaction.import_id !== undefined)
+						payload.import_id = transaction.import_id;
+
+					return payload;
+				},
+			);
+
+			const response = await ynabAPI.transactions.createTransactions(
+				budget_id,
+				{
+					transactions: saveTransactions,
+				},
+			);
+
+			const responseData = response.data;
+			const duplicateImportIds = new Set(
+				responseData.duplicate_import_ids ?? [],
+			);
+			const results = correlateResults(
+				transactions,
+				responseData,
+				duplicateImportIds,
+			);
+
+			const summary = {
+				total_requested: transactions.length,
+				created: responseData.transaction_ids?.length ?? 0,
+				duplicates: duplicateImportIds.size,
+				failed: results.filter((result) => result.status === "failed").length,
+			};
+
+			const baseResponse: BulkCreateResponse = {
+				success: summary.failed === 0,
+				server_knowledge: responseData.server_knowledge,
+				summary,
+				results,
+				transactions: responseData.transactions ?? [],
+				duplicate_import_ids: responseData.duplicate_import_ids ?? [],
+				message: `Processed ${summary.total_requested} transactions: ${summary.created} created, ${summary.duplicates} duplicates, ${summary.failed} failed.`,
+			};
+
+			const accountIds = new Set<string>(
+				transactions.map((transaction) => transaction.account_id),
+			);
+			const affectedMonths = new Set<string>(
+				transactions.map((transaction) => toMonthKey(transaction.date)),
+			);
+			const affectedCategoryIds = new Set<string>();
+			for (const created of responseData.transactions ?? []) {
+				appendCategoryIds(created, affectedCategoryIds);
+			}
+			invalidateTransactionCaches(
+				deltaCache,
+				knowledgeStore,
+				budget_id,
+				responseData.server_knowledge,
+				accountIds,
+				affectedMonths,
+				{
+					affectedCategoryIds,
+					accountTotalsChanged: true,
+					invalidateMonths: true,
+				},
+			);
+
+			const finalizedResponse = finalizeResponse(baseResponse);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format(finalizedResponse),
+					},
+				],
+			};
+		},
+		"ynab:create_transactions",
+		"bulk transaction creation",
+		errorHandler,
+	)) as CallToolResult;
+}
+
+/**
+ * Interface for transaction metadata needed for cache invalidation
+ */
+interface TransactionMetadata {
+	account_id: string;
+	date: string;
+}
+
+/**
+ * Result of metadata resolution including both resolved metadata and unresolved IDs
+ */
+interface MetadataResolutionResult {
+	metadata: Map<string, TransactionMetadata>;
+	unresolvedIds: string[];
+	previewDetails: Map<string, ynab.TransactionDetail>;
+}
+
+interface ResolveMetadataOptions {
+	previewTransactionIds?: string[];
+}
+
+/**
+ * Resolves metadata for bulk update transactions
+ * Uses a multi-tier approach: request metadata -> cache -> limited API calls
+ * Returns both the resolved metadata and a list of IDs that could not be resolved
+ */
+async function resolveMetadata(
+	ynabAPI: ynab.API,
+	budgetId: string,
+	transactions: BulkUpdateTransactionInput[],
+	options: ResolveMetadataOptions = {},
+): Promise<MetadataResolutionResult> {
+	const metadata = new Map<string, TransactionMetadata>();
+	const needsResolution: string[] = [];
+	const previewIds = new Set(options.previewTransactionIds ?? []);
+	const previewDetails = new Map<string, ynab.TransactionDetail>();
+	const previewIdsNeedingFetch = new Set(previewIds);
+
+	// First pass: Use provided metadata
+	for (const transaction of transactions) {
+		if (transaction.original_account_id && transaction.original_date) {
+			metadata.set(transaction.id, {
+				account_id: transaction.original_account_id,
+				date: transaction.original_date,
+			});
+		} else {
+			needsResolution.push(transaction.id);
+		}
+	}
+
+	if (previewIds.size === 0 && needsResolution.length === 0) {
+		return { metadata, unresolvedIds: [], previewDetails };
+	}
+
+	// Second pass: hydrate from cache for both metadata needs and preview requests
+	const needsResolutionSet = new Set(needsResolution);
+	const cacheLookupIds = new Set<string>([...needsResolution, ...previewIds]);
+	for (const transactionId of cacheLookupIds) {
+		const cacheKey = CacheManager.generateKey(
+			"transaction",
+			"get",
+			budgetId,
+			transactionId,
+		);
+		const cached = cacheManager.get<ynab.TransactionDetail>(cacheKey);
+		if (!cached) {
+			continue;
+		}
+
+		if (needsResolutionSet.has(transactionId)) {
+			metadata.set(transactionId, {
+				account_id: cached.account_id,
+				date: cached.date,
+			});
+			needsResolutionSet.delete(transactionId);
+		}
+		if (previewIds.has(transactionId) && !previewDetails.has(transactionId)) {
+			previewDetails.set(transactionId, cached);
+			previewIdsNeedingFetch.delete(transactionId);
+		}
+	}
+
+	const stillNeedsResolution = Array.from(needsResolutionSet);
+	if (stillNeedsResolution.length === 0 && previewIdsNeedingFetch.size === 0) {
+		return { metadata, unresolvedIds: [], previewDetails };
+	}
+
+	// Third pass: Limited API calls with concurrency limit
+	const MAX_CONCURRENT_FETCHES = 5;
+	const fetchPromises: Promise<void>[] = [];
+	const metadataAwaitingResolution = new Set(stillNeedsResolution);
+	const idsNeedingApiFetch = Array.from(
+		new Set([...stillNeedsResolution, ...previewIdsNeedingFetch]),
+	);
+
+	for (let i = 0; i < idsNeedingApiFetch.length; i += MAX_CONCURRENT_FETCHES) {
+		const batch = idsNeedingApiFetch.slice(i, i + MAX_CONCURRENT_FETCHES);
+		const batchPromises = batch.map(async (transactionId) => {
+			try {
+				const response = await ynabAPI.transactions.getTransactionById(
+					budgetId,
+					transactionId,
+				);
+				const transaction = response.data.transaction;
+				if (transaction) {
+					if (metadataAwaitingResolution.has(transactionId)) {
+						metadata.set(transactionId, {
+							account_id: transaction.account_id,
+							date: transaction.date,
+						});
+						metadataAwaitingResolution.delete(transactionId);
+					}
+					if (
+						previewIdsNeedingFetch.has(transactionId) &&
+						!previewDetails.has(transactionId)
+					) {
+						previewDetails.set(transactionId, transaction);
+						previewIdsNeedingFetch.delete(transactionId);
+					}
+				}
+			} catch {
+				if (metadataAwaitingResolution.has(transactionId)) {
+					globalRequestLogger.logError(
+						"ynab:update_transactions",
+						"resolve_metadata",
+						{ transaction_id: transactionId },
+						"Failed to resolve transaction metadata",
+					);
+				}
+			}
+		});
+		fetchPromises.push(...batchPromises);
+	}
+
+	await Promise.all(fetchPromises);
+	return {
+		metadata,
+		unresolvedIds: Array.from(metadataAwaitingResolution),
+		previewDetails,
+	};
+}
+
+/**
+ * Handles the ynab:update_transactions tool call
+ * Updates multiple transactions in a single batch operation
+ */
+export async function handleUpdateTransactions(
+	ynabAPI: ynab.API,
+	deltaCache: DeltaCache,
+	knowledgeStore: ServerKnowledgeStore,
+	params: UpdateTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleUpdateTransactions(
+	ynabAPI: ynab.API,
+	params: UpdateTransactionsParams,
+): Promise<CallToolResult>;
+export async function handleUpdateTransactions(
+	ynabAPI: ynab.API,
+	deltaCacheOrParams: DeltaCache | UpdateTransactionsParams,
+	knowledgeStoreOrParams?: ServerKnowledgeStore | UpdateTransactionsParams,
+	maybeParams?: UpdateTransactionsParams,
+	errorHandler?: ErrorHandler,
+): Promise<CallToolResult> {
+	const { deltaCache, knowledgeStore, params } = resolveDeltaWriteArgs(
+		deltaCacheOrParams,
+		knowledgeStoreOrParams,
+		maybeParams,
+	);
+	return (await withToolErrorHandling(
+		async () => {
+			const validationResult = UpdateTransactionsSchema.safeParse(params);
+			if (!validationResult.success) {
+				type TransactionIssueIndex = number | null;
+				const issuesByIndex = new Map<TransactionIssueIndex, string[]>();
+				const validationIssues = validationResult.error.issues ?? [];
+				for (const issue of validationIssues) {
+					const transactionIndex = issue.path.find(
+						(segment): segment is number => typeof segment === "number",
+					);
+					const message = issue.message;
+					const issueIndex: TransactionIssueIndex =
+						transactionIndex !== undefined ? transactionIndex : null;
+					const existing = issuesByIndex.get(issueIndex) ?? [];
+					existing.push(message);
+					issuesByIndex.set(issueIndex, existing);
+				}
+
+				const details = Array.from(issuesByIndex.entries()).map(
+					([index, errors]) => ({
+						transaction_index: index,
+						errors,
+					}),
+				);
+
+				throw new ValidationError(
+					"Bulk transaction update validation failed",
+					JSON.stringify(details, null, 2),
+					[
+						"Ensure each transaction includes an id field",
+						"Limit batches to 100 items",
+					],
+				);
+			}
+
+			const { budget_id, transactions, dry_run } = validationResult.data;
+
+			if (dry_run) {
+				const previewTransactions = transactions.slice(0, 10);
+				const previewTransactionIds = previewTransactions.map(
+					(transaction) => transaction.id,
+				);
+				// Resolve metadata once and reuse any transaction details for preview rendering
+				const { metadata, unresolvedIds, previewDetails } =
+					await resolveMetadata(ynabAPI, budget_id, transactions, {
+						previewTransactionIds,
+					});
+
+				const transactionsPreview = [];
+				const unavailablePreviewIds: string[] = [];
+
+				for (const transaction of previewTransactions) {
+					const currentState = previewDetails.get(transaction.id);
+					if (!currentState) {
+						unavailablePreviewIds.push(transaction.id);
+						transactionsPreview.push({
+							transaction_id: transaction.id,
+							before: "unavailable",
+							after: transaction,
+						});
+						continue;
+					}
+
+					const before: Record<string, unknown> = {};
+					const after: Record<string, unknown> = {};
+
+					if (
+						transaction.amount !== undefined &&
+						transaction.amount !== currentState.amount
+					) {
+						before["amount"] = milliunitsToAmount(currentState.amount);
+						after["amount"] = milliunitsToAmount(transaction.amount);
+					}
+					if (
+						transaction.date !== undefined &&
+						transaction.date !== currentState.date
+					) {
+						before["date"] = currentState.date;
+						after["date"] = transaction.date;
+					}
+					if (
+						transaction.memo !== undefined &&
+						transaction.memo !== currentState.memo
+					) {
+						before["memo"] = currentState.memo;
+						after["memo"] = transaction.memo;
+					}
+					if (
+						transaction.payee_id !== undefined &&
+						transaction.payee_id !== currentState.payee_id
+					) {
+						before["payee_id"] = currentState.payee_id;
+						after["payee_id"] = transaction.payee_id;
+					}
+					if (
+						transaction.payee_name !== undefined &&
+						transaction.payee_name !== currentState.payee_name
+					) {
+						before["payee_name"] = currentState.payee_name;
+						after["payee_name"] = transaction.payee_name;
+					}
+					if (
+						transaction.category_id !== undefined &&
+						transaction.category_id !== currentState.category_id
+					) {
+						before["category_id"] = currentState.category_id;
+						after["category_id"] = transaction.category_id;
+					}
+					if (
+						transaction.cleared !== undefined &&
+						transaction.cleared !== currentState.cleared
+					) {
+						before["cleared"] = currentState.cleared;
+						after["cleared"] = transaction.cleared;
+					}
+					if (
+						transaction.approved !== undefined &&
+						transaction.approved !== currentState.approved
+					) {
+						before["approved"] = currentState.approved;
+						after["approved"] = transaction.approved;
+					}
+					if (
+						transaction.flag_color !== undefined &&
+						transaction.flag_color !== currentState.flag_color
+					) {
+						before["flag_color"] = currentState.flag_color;
+						after["flag_color"] = transaction.flag_color;
+					}
+
+					transactionsPreview.push({
+						transaction_id: transaction.id,
+						before,
+						after,
+					});
+				}
+
+				// Build warnings array
+				const warnings: {
+					code: string;
+					count: number;
+					message: string;
+					sample_ids?: string[];
+				}[] = [];
+				if (unavailablePreviewIds.length > 0 || unresolvedIds.length > 0) {
+					const totalMissing = Math.max(
+						unavailablePreviewIds.length,
+						unresolvedIds.length,
+					);
+					const sampleIds =
+						unresolvedIds.length > 0
+							? unresolvedIds.slice(0, 10)
+							: unavailablePreviewIds.slice(0, 10);
+					warnings.push({
+						code: "metadata_unavailable",
+						count: totalMissing,
+						message: `Unable to fetch prior state for ${totalMissing} transactions`,
+						sample_ids: sampleIds,
+					});
+				}
+
+				// Collect summary statistics
+				const accountsAffected = Array.from(
+					new Set(Array.from(metadata.values()).map((m) => m.account_id)),
+				);
+				const fieldsToUpdate = new Set<string>();
+				for (const transaction of transactions) {
+					if (transaction.amount !== undefined) fieldsToUpdate.add("amount");
+					if (transaction.date !== undefined) fieldsToUpdate.add("date");
+					if (transaction.memo !== undefined) fieldsToUpdate.add("memo");
+					if (transaction.payee_id !== undefined)
+						fieldsToUpdate.add("payee_id");
+					if (transaction.payee_name !== undefined)
+						fieldsToUpdate.add("payee_name");
+					if (transaction.category_id !== undefined)
+						fieldsToUpdate.add("category_id");
+					if (transaction.cleared !== undefined) fieldsToUpdate.add("cleared");
+					if (transaction.approved !== undefined)
+						fieldsToUpdate.add("approved");
+					if (transaction.flag_color !== undefined)
+						fieldsToUpdate.add("flag_color");
+				}
+
+				const response: Record<string, unknown> = {
+					dry_run: true,
+					action: "update_transactions",
+					validation: "passed",
+					summary: {
+						total_transactions: transactions.length,
+						accounts_affected: accountsAffected,
+						fields_to_update: Array.from(fieldsToUpdate),
+					},
+					transactions_preview: transactionsPreview,
+					note: "Dry run complete. No transactions updated. No caches invalidated. No server_knowledge updated.",
+				};
+
+				if (warnings.length > 0) {
+					response["warnings"] = warnings;
+				}
+
+				return {
+					content: [
+						{
+							type: "text",
+							text: responseFormatter.format(response),
+						},
+					],
+				};
+			}
+
+			// Resolve metadata for cache invalidation before making updates
+			const { metadata, unresolvedIds } = await resolveMetadata(
+				ynabAPI,
+				budget_id,
+				transactions,
+			);
+
+			// Check metadata completeness threshold (5%)
+			const missingMetadataRatio = unresolvedIds.length / transactions.length;
+			const METADATA_THRESHOLD = 0.05; // 5%
+
+			if (missingMetadataRatio > METADATA_THRESHOLD) {
+				throw new ValidationError(
+					`METADATA_INCOMPLETE: ${(missingMetadataRatio * 100).toFixed(1)}% of transactions have missing metadata (threshold: ${(METADATA_THRESHOLD * 100).toFixed(0)}%)`,
+					JSON.stringify(
+						{
+							unresolved_count: unresolvedIds.length,
+							total_transactions: transactions.length,
+							ratio: `${(missingMetadataRatio * 100).toFixed(1)}%`,
+							threshold: `${(METADATA_THRESHOLD * 100).toFixed(0)}%`,
+							sample_unresolved_ids: unresolvedIds.slice(0, 5),
+						},
+						null,
+						2,
+					),
+					[
+						"Provide original_account_id and original_date for all transactions being updated",
+						"Ensure transactions exist in YNAB before updating them",
+					],
+				);
+			}
+
+			if (missingMetadataRatio > 0.01) {
+				globalRequestLogger.logRequest(
+					"ynab:update_transactions",
+					"metadata_resolution_warning",
+					{
+						unresolved_count: unresolvedIds.length,
+						total_transactions: transactions.length,
+						ratio: missingMetadataRatio.toFixed(3),
+						sample_ids: unresolvedIds.slice(0, 5),
+						message: "Metadata resolution incomplete for some transactions",
+					},
+					true,
+				);
+			}
+
+			// Prepare update transactions for the YNAB API
+			const updateTransactions: { id: string; transaction: SaveTransaction }[] =
+				transactions.map((transaction) => {
+					const transactionData: SaveTransaction = {};
+
+					// Note: account_id is intentionally excluded as account moves are not supported
+					if (transaction.amount !== undefined) {
+						transactionData.amount = transaction.amount;
+					}
+					if (transaction.date !== undefined) {
+						transactionData.date = transaction.date;
+					}
+					if (transaction.payee_name !== undefined) {
+						transactionData.payee_name = transaction.payee_name;
+					}
+					if (transaction.payee_id !== undefined) {
+						transactionData.payee_id = transaction.payee_id;
+					}
+					if (transaction.category_id !== undefined) {
+						transactionData.category_id = transaction.category_id;
+					}
+					if (transaction.memo !== undefined) {
+						transactionData.memo = transaction.memo;
+					}
+					if (transaction.cleared !== undefined) {
+						transactionData.cleared =
+							transaction.cleared as ynab.TransactionClearedStatus;
+					}
+					if (transaction.approved !== undefined) {
+						transactionData.approved = transaction.approved;
+					}
+					if (transaction.flag_color !== undefined) {
+						transactionData.flag_color =
+							transaction.flag_color as ynab.TransactionFlagColor;
+					}
+
+					return {
+						id: transaction.id,
+						transaction: transactionData,
+					};
+				});
+
+			// Execute bulk update
+			const response = await ynabAPI.transactions.updateTransactions(
+				budget_id,
+				{
+					transactions: updateTransactions,
+				},
+			);
+
+			const responseData = response.data;
+			const updatedTransactions = responseData.transactions ?? [];
+
+			// Build results
+			const results: BulkUpdateResult[] = [];
+			const updatedIds = new Set(updatedTransactions.map((t) => t.id));
+
+			for (const [index, transaction] of transactions.entries()) {
+				if (updatedIds.has(transaction.id)) {
+					results.push({
+						request_index: index,
+						status: "updated",
+						transaction_id: transaction.id,
+						correlation_key: transaction.id,
+					});
+				} else {
+					results.push({
+						request_index: index,
+						status: "failed",
+						transaction_id: transaction.id,
+						correlation_key: transaction.id,
+						error_code: "update_failed",
+						error: "Transaction was not updated by YNAB API",
+					});
+				}
+			}
+
+			const summary = {
+				total_requested: transactions.length,
+				updated: updatedTransactions.length,
+				failed: results.filter((r) => r.status === "failed").length,
+			};
+
+			const baseResponse: BulkUpdateResponse = {
+				success: summary.failed === 0,
+				server_knowledge: responseData.server_knowledge,
+				summary,
+				results,
+				transactions: updatedTransactions,
+				message: `Processed ${summary.total_requested} transactions: ${summary.updated} updated, ${summary.failed} failed.`,
+			};
+
+			for (const transaction of transactions) {
+				cacheManager.delete(
+					CacheManager.generateKey(
+						"transaction",
+						"get",
+						budget_id,
+						transaction.id,
+					),
+				);
+			}
+
+			const affectedAccountIds = new Set<string>();
+			const affectedMonthKeys = new Set<string>();
+			const affectedCategoryIds = new Set<string>();
+			let invalidateAllCategories = false;
+			let accountTotalsChanged = false;
+			let monthsImpacted = false;
+
+			for (const transaction of transactions) {
+				const meta = metadata.get(transaction.id);
+				const amountChanged = transaction.amount !== undefined;
+				const clearedChanged = transaction.cleared !== undefined;
+				const categoryChanged = transaction.category_id !== undefined;
+				const dateChanged = transaction.date !== undefined;
+
+				if ((amountChanged || clearedChanged) && meta) {
+					affectedAccountIds.add(meta.account_id);
+				}
+
+				if (amountChanged) {
+					monthsImpacted = true;
+					accountTotalsChanged = true;
+					invalidateAllCategories = true;
+					if (meta) {
+						affectedMonthKeys.add(toMonthKey(meta.date));
+					}
+				}
+
+				if (categoryChanged) {
+					monthsImpacted = true;
+					invalidateAllCategories = true;
+					if (transaction.category_id) {
+						affectedCategoryIds.add(transaction.category_id);
+					}
+					if (meta) {
+						affectedMonthKeys.add(toMonthKey(meta.date));
+					}
+				}
+
+				if (dateChanged && meta) {
+					monthsImpacted = true;
+					affectedMonthKeys.add(toMonthKey(meta.date));
+				}
+				if (dateChanged && transaction.date) {
+					affectedMonthKeys.add(toMonthKey(transaction.date));
+				}
+			}
+
+			invalidateTransactionCaches(
+				deltaCache,
+				knowledgeStore,
+				budget_id,
+				responseData.server_knowledge,
+				affectedAccountIds,
+				affectedMonthKeys,
+				{
+					affectedCategoryIds,
+					invalidateAllCategories,
+					accountTotalsChanged,
+					invalidateMonths: monthsImpacted,
+				},
+			);
+
+			const finalizedResponse = finalizeBulkUpdateResponse(baseResponse);
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: responseFormatter.format(finalizedResponse),
+					},
+				],
+			};
+		},
+		"ynab:update_transactions",
+		"bulk transaction update",
+		errorHandler,
+	)) as CallToolResult;
+}
+
+/**
+ * Registers write transaction tools with the provided registry.
+ */
+export function registerTransactionWriteTools(
+	registry: ToolRegistry,
+	context: ToolContext,
+): void {
+	const { adaptWrite } = createAdapters(context);
+	const budgetResolver = createBudgetResolver(context);
+
+	registry.register({
+		name: "create_transaction",
+		description: "Create a new transaction in the specified budget and account",
+		inputSchema: CreateTransactionSchema,
+		handler: adaptWrite(handleCreateTransaction),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof CreateTransactionSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+				title: "YNAB: Create Transaction",
+			},
+		},
+	});
+
+	registry.register({
+		name: "create_transactions",
+		description:
+			"Create multiple transactions in a single batch (1-100 items) with duplicate detection, dry-run validation, and automatic response size management with correlation metadata.",
+		inputSchema: CreateTransactionsSchema,
+		handler: adaptWrite(handleCreateTransactions),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof CreateTransactionsSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+				title: "YNAB: Create Multiple Transactions",
+			},
+		},
+	});
+
+	registry.register({
+		name: "create_receipt_split_transaction",
+		description:
+			"Create a split transaction from receipt items with proportional tax allocation",
+		inputSchema: CreateReceiptSplitTransactionSchema,
+		handler: adaptWrite(handleCreateReceiptSplitTransaction),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof CreateReceiptSplitTransactionSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_CREATE,
+				title: "YNAB: Create Split Transaction from Receipt",
+			},
+		},
+	});
+
+	registry.register({
+		name: "update_transaction",
+		description: "Update an existing transaction",
+		inputSchema: UpdateTransactionSchema,
+		handler: adaptWrite(handleUpdateTransaction),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof UpdateTransactionSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+				title: "YNAB: Update Transaction",
+			},
+		},
+	});
+
+	registry.register({
+		name: "update_transactions",
+		description:
+			"Update multiple transactions in a single batch (1-100 items) with dry-run validation, automatic cache invalidation, and response size management. Supports optional original_account_id and original_date metadata for efficient cache invalidation.",
+		inputSchema: UpdateTransactionsSchema,
+		handler: adaptWrite(handleUpdateTransactions),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof UpdateTransactionsSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_UPDATE,
+				title: "YNAB: Update Multiple Transactions",
+			},
+		},
+	});
+
+	registry.register({
+		name: "delete_transaction",
+		description: "Delete a transaction from the specified budget",
+		inputSchema: DeleteTransactionSchema,
+		handler: adaptWrite(handleDeleteTransaction),
+		defaultArgumentResolver:
+			budgetResolver<z.infer<typeof DeleteTransactionSchema>>(),
+		metadata: {
+			annotations: {
+				...ToolAnnotationPresets.WRITE_EXTERNAL_DELETE,
+				title: "YNAB: Delete Transaction",
+			},
+		},
+	});
+}