actual-mcp-server 0.22.13 → 0.22.17

package/dist/src/tools/budget_updates_batch.js

@@ -1,30 +1,34 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { CommonSchemas } from '../lib/schemas/common.js';
-import api from '@actual-app/api';
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-const { setBudgetAmount: rawSetBudgetAmount, setBudgetCarryover: rawSetBudgetCarryover } = api;
-const BudgetOperationSchema = z.object({
+import { createModuleLogger } from '../lib/loggerFactory.js';
+const log = createModuleLogger('BUDGET_BATCH');
+const BudgetOperationSchema = z
+    .object({
     month: z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/, 'month must be in YYYY-MM format (e.g. 2025-01)').describe('Budget month in YYYY-MM format'),
     categoryId: CommonSchemas.categoryId.describe('Category ID'),
-    amount: z.number().optional().describe('Budget amount in cents (if setting amount)'),
+    amount: CommonSchemas.amountCents.optional().describe('Budget amount in integer cents (if setting amount)'),
     carryover: z.boolean().optional().describe('Carryover flag (if setting carryover)'),
+})
+    .refine((op) => op.amount !== undefined || op.carryover !== undefined, {
+    message: 'each operation needs at least one of amount or carryover',
 });
 const InputSchema = z.object({
-    operations: z.array(BudgetOperationSchema).describe('Array of budget operations to perform in batch'),
+    operations: z.array(BudgetOperationSchema).min(1).max(100).describe('Array of 1 to 100 budget operations to perform in batch'),
 });
+// Legacy ToolDefinition (like its sibling actual_transactions_update_batch): this is a
+// correctness fix, and a createTool() migration would widen the diff with no benefit to it.
+// The guards, the single write cycle and the raw writes all live in adapter.setBudgetBatch;
+// this file never imports @actual-app/api and never writes directly (AGENTS.md).
 const tool = {
     name: 'actual_budget_updates_batch',
-    description: `Perform multiple budget updates in a single batch operation. More efficient than individual calls for bulk budget changes.
+    description: `Set budget amounts and/or carryover flags for many month/category pairs in one call. Accepts 1 to 100 operations; each operation needs at least one of amount (integer cents) or carryover (boolean).
 
-Use cases:
-- Set budget amounts for multiple months/categories at once
-- Copy budgets across time periods
-- Bulk budget initialization
+Each operation is applied independently and NOT atomically: there is no rollback, so items applied before a failure stay applied. An unknown category, a month outside the budget's range, or a carryover on an income category fails only that item and is reported per item. If an operation sets both amount and carryover and the carryover fails, the amount may already be applied. If the call times out, read the affected months back with actual_budgets_getMonth BEFORE retrying; some items may have been applied. If several items target the same month and category, the last one wins.
 
-Limits: Recommended max 50 operations per batch to avoid timeouts.
+Returns: { succeeded: [{index, month, categoryId}], failed: [{index, month, categoryId, error}], total, successCount, failureCount }. Every item failing is a normal result (successCount 0), not a tool error. To rebalance categories, read the month with actual_budgets_getMonth, then send one batch of absolute amounts.
 
-Example: Set health insurance budget for 12 months:
+Example: Set health insurance budget for 2 months:
 {
   "operations": [
     {"month": "2025-01", "categoryId": "<uuid>", "amount": 50000},
@@ -33,46 +37,27 @@ Example: Set health insurance budget for 12 months:
 }`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
+        // No catch-all (#517): a ZodError or a whole-call failure (budget precondition, lock,
+        // timeout) must reach actualToolsManager.callTool and surface as a tool error.
         const input = InputSchema.parse(args || {});
-        // Validate operation count
-        if (input.operations.length > 100) {
-            throw new Error(`Too many operations (${input.operations.length}). Maximum 100 per batch. Split into multiple batches.`);
-        }
-        if (input.operations.length > 50) {
-            console.warn(`Large batch (${input.operations.length} operations). Consider splitting for better reliability.`);
-        }
-        // Track successes and failures
-        const results = { successful: 0, failed: 0, errors: [] };
-        // Use batchBudgetUpdates to wrap all operations in a single transaction
-        await adapter.batchBudgetUpdates(async () => {
-            for (let i = 0; i < input.operations.length; i++) {
-                const op = input.operations[i];
-                try {
-                    // Use raw API calls directly to avoid nested queueing/deadlock
-                    if (op.amount !== undefined) {
-                        await rawSetBudgetAmount(op.month, op.categoryId, op.amount);
-                    }
-                    if (op.carryover !== undefined) {
-                        await rawSetBudgetCarryover(op.month, op.categoryId, op.carryover);
-                    }
-                    results.successful++;
-                }
-                catch (error) {
-                    results.failed++;
-                    const errorMsg = `Operation ${i + 1} failed (month: ${op.month}, category: ${op.categoryId}): ${error.message}`;
-                    results.errors.push(errorMsg);
-                    console.error(errorMsg);
-                    // Continue processing remaining operations
-                }
-            }
+        const { succeeded, failed } = await adapter.setBudgetBatch(input.operations);
+        // Counts, plus index/month/categoryId per failure. Never amounts.
+        log.info('Budget batch finished', {
+            total: input.operations.length,
+            successCount: succeeded.length,
+            failureCount: failed.length,
         });
-        return {
-            success: results.failed === 0,
-            totalOperations: input.operations.length,
-            successful: results.successful,
-            failed: results.failed,
-            errors: results.errors.length > 0 ? results.errors.slice(0, 5) : undefined, // Return first 5 errors
+        for (const f of failed) {
+            log.warn('Budget batch item failed', { index: f.index, month: f.month, categoryId: f.categoryId });
+        }
+        const result = {
+            succeeded,
+            failed,
+            total: input.operations.length,
+            successCount: succeeded.length,
+            failureCount: failed.length,
         };
+        return result;
     },
 };
 export default tool;

package/dist/src/tools/index.js

@@ -46,6 +46,7 @@ export { default as get_id_by_name } from './get_id_by_name.js';
 export { default as server_get_version } from './server_get_version.js';
 export { default as query_run } from './query_run.js';
 export { default as rules_create } from './rules_create.js';
+export { default as rules_create_batch } from './rules_create_batch.js';
 export { default as rules_create_or_update } from './rules_create_or_update.js';
 export { default as rules_delete } from './rules_delete.js';
 export { default as rules_get } from './rules_get.js';

package/dist/src/tools/query_run.js

@@ -6,57 +6,21 @@ const InputSchema = z.object({
 });
 const tool = {
     name: 'actual_query_run',
-    description: `Execute SQL queries for advanced financial data analysis.
+    description: `Run a read-only SQL query against the budget data. Prefer SQL; a bare table name (e.g. "transactions") returns all its records.
 
-**RECOMMENDED: Use SQL syntax** - Most reliable and well-tested format.
+Form: SELECT [fields] FROM [table] WHERE [conditions] ORDER BY [field] DESC LIMIT [n]
+Example: "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 ORDER BY date DESC LIMIT 10"
 
-SQL SYNTAX (Preferred):
-  SELECT [fields] FROM [table] WHERE [conditions] ORDER BY [field] DESC LIMIT [n]
-  
-  Examples:
-  • "SELECT * FROM transactions ORDER BY date DESC LIMIT 5"
-  • "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 LIMIT 10"
-  • "SELECT id, date, amount, category.name FROM transactions WHERE date >= '2025-01-01'"
+WHERE supports: =, !=, >, >=, <, <=; IN (v1, v2); LIKE / NOT LIKE (case and accent-insensitive, % wildcard, e.g. imported_payee LIKE '%amazon%'); IS NULL / IS NOT NULL; boolean columns as true / false (cleared = false, category.hidden = true); conditions joined with AND. OR, REGEXP, NOT IN and parenthesised groups are not supported and return an error (a query is never silently run unfiltered). Transactions come back in split-INLINE mode: "is_parent = true" returns nothing, use "is_parent = false" to exclude split children.
 
-Supported WHERE operators:
-  • Comparison: =, !=, >, >=, <, <=
-  • IN (v1, v2, ...)
-  • LIKE / NOT LIKE for pattern search (case-insensitive, accent-insensitive; use % as wildcard)
-    e.g. "WHERE imported_payee LIKE '%amazon%'" to find raw bank-sync payee strings
-  • IS NULL / IS NOT NULL e.g. "WHERE imported_payee IS NULL" to find unmerged rows
-  • Boolean columns take true / false (case-insensitive; 1 / 0 also accepted)
-    e.g. "WHERE cleared = false" for uncleared, "WHERE reconciled = true",
-    "WHERE category.hidden = true", "WHERE account.closed = true"
-    Note: transactions are returned in split-INLINE mode, so "WHERE is_parent = true" returns
-    nothing (parent rows are hidden); use "is_parent = false" to exclude split children.
-  • Combine conditions with AND. OR, REGEXP, NOT IN, and parenthesised groups are not yet
-    supported and will return an error (the query is never silently run unfiltered).
+Joins use dot notation: payee.name, category.name, account.name (NOT payee_name). Amounts are in cents: $100.00 = 10000.
 
-IMPORTANT - Field Names:
-  • Use payee.name (NOT payee_name) for payee names
-  • Use category.name (NOT category_name) for category names
-  • Use account.name (NOT account_name) for account names
-  • Amounts are in cents: $100.00 = 10000
-
-Available Tables:
-  • transactions: id, date, amount, notes, cleared, account, payee, category
-    - Join with: payee.name, category.name, account.name
-  • accounts: id, name, type, closed, offbudget
-  • categories: id, name, group, is_income
-  • payees: id, name
-  • category_groups: id, name, is_income
-
-Common Queries:
-  • Last 5 transactions: "SELECT * FROM transactions ORDER BY date DESC LIMIT 5"
-  • By category: "SELECT id, date, amount, payee.name FROM transactions WHERE category.name = 'Food' LIMIT 10"
-  • Expenses: "SELECT id, date, amount, payee.name FROM transactions WHERE amount < 0 ORDER BY date DESC LIMIT 10"
-  • Date range: "SELECT * FROM transactions WHERE date >= '2025-01-01' AND date <= '2025-12-31'"
-
-Alternative Formats:
-  • Simple table name: "transactions" (returns all records)
-  • ActualQL objects: Not recommended, use SQL instead
-
-For details: https://actualbudget.org/docs/api/actual-ql/`,
+Tables:
+- transactions: id, date, amount, notes, cleared, account, payee, category
+- accounts: id, name, type, closed, offbudget
+- categories: id, name, group, is_income
+- payees: id, name
+- category_groups: id, name, is_income`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         try {

package/dist/src/tools/rules_create.js

@@ -1,140 +1,17 @@
-import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-// Define the schema for rule conditions and actions
-const ConditionSchema = z.object({
-    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category")'),
-    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
-    value: z.union([z.string(), z.number()]).describe('Value to match against'),
-    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
-});
-const ActionSchema = z.object({
-    op: z.string()
-        .default('set')
-        .describe('Operation to perform. Options: "set" (default, assign value to field), "set-split-amount" (split transaction), "link-schedule" (link to scheduled transaction), "prepend-notes" (add text before notes), "append-notes" (add text after notes)'),
-    field: z.string()
-        .optional()
-        .describe('Field to modify - required for "set" operation. Options: "category" (transaction category), "payee" (transaction payee), "notes" (transaction notes), "cleared" (cleared status), "account" (move to different account)'),
-    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()])
-        .describe('Value to assign. Use category/payee/account UUID for "id" types, text for "string" types, number for amounts'),
-    type: z.string()
-        .optional()
-        .describe('Value type hint. Options: "id" (UUID for category/payee/account), "string" (text value), "number" (numeric value), "boolean" (true/false)'),
-    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
-});
-// Operator validation map
-const FIELD_OPERATORS = {
-    'imported_payee': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
-    'payee': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
-    'account': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
-    'category': { type: 'id', operators: ['is', 'isNot', 'oneOf', 'notOneOf'] },
-    'notes': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
-    'description': { type: 'string', operators: ['contains', 'matches', 'doesNotContain', 'is', 'isNot'] },
-    'amount': { type: 'number', operators: ['is', 'gte', 'lte', 'gt', 'lt', 'isapprox'] },
-    'date': { type: 'date', operators: ['is', 'gte', 'lte', 'gt', 'lt'] },
-};
-const InputSchema = z.object({
-    // #342: three stages, and the default one is `null`, not a string.
-    //
-    // Verified against Actual's validator (transaction-rules.ts) and a live server:
-    // it accepts exactly 'pre', 'post' and null, and REJECTS the literal "default"
-    // with `Invalid rule stage: default`. The published API reference says
-    // pre/default/post, which is wrong in both directions (reported upstream as
-    // actualbudget/actual#8682).
-    //
-    // The default here MUST be null and must be SENT. Two traps:
-    //   - Defaulting to 'pre' (what this did until #342) silently puts every
-    //     MCP-created rule ahead of every rule the user made in the UI, because
-    //     Actual runs stages in the order pre, default, post. No error, no warning.
-    //   - Simply making it .optional() and omitting the key does NOT work: on a
-    //     create the validator always runs and rejects `undefined` with
-    //     `Invalid rule stage: undefined`.
-    stage: z
-        .enum(['pre', 'post'])
-        .nullable()
-        .optional()
-        .default(null)
-        .describe('When to apply the rule. null (the default) is Actual\'s normal stage, the one a rule gets in the UI ' +
-        'when no stage is chosen. "pre" runs before the default stage, "post" after. Leave unset unless you ' +
-        'specifically need the rule to out-rank or defer to the user\'s existing rules.'),
-    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
-    conditions: z.array(ConditionSchema).describe('Array of conditions that must be met for the rule to apply'),
-    actions: z.array(ActionSchema).describe('Array of actions to perform when conditions are met'),
-});
+import { CONDITION_OPERATORS_HELP, RuleItemSchema, validateRuleInput } from '../lib/schemas/rules.js';
 const tool = {
     name: 'actual_rules_create',
-    description: `Create a new budget rule with conditions and actions.
-
-IMPORTANT Field Types:
-- "imported_payee" (string) - for text matching payee names. Supports: contains, matches, doesNotContain, is, isNot
-- "payee" (ID) - for exact payee ID matching. Supports: is, isNot, oneOf, notOneOf
-- "account", "category" (ID) - for account/category IDs. Supports: is, isNot, oneOf, notOneOf
-- "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
-- "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
-
-Stage: omit it (the normal stage, recommended), or 'pre' to run before the user's own rules, or 'post' to run after.
-Do NOT pass "default" as a string; Actual rejects it. The normal stage is null, which is what omitting gives you.
-Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
+    description: `Create a budget rule.
 
-Example (no stage, so the rule lands in the normal stage alongside the user's own rules): {conditionsOp: "and", conditions: [{field: "imported_payee", op: "contains", value: "Amazon"}], actions: [{op: "set", field: "category", value: "category-uuid"}]}`,
-    inputSchema: InputSchema,
+${CONDITION_OPERATORS_HELP}
+Stage: omit it for the normal stage (recommended), or 'pre' / 'post'. Do NOT pass "default"; it is rejected.
+Category, payee and account ids in conditions or actions must exist, or the call is refused with a not-found error and nothing is created (ids in link-schedule actions are not checked).`,
+    inputSchema: RuleItemSchema,
     call: async (args, _meta) => {
         // Zod validation errors are formatted centrally by actualToolsManager (#206).
-        const input = InputSchema.parse(args || {});
-        // Validate that actions with op="set" have a field
-        for (const action of input.actions) {
-            if (action.op === 'set' && !action.field) {
-                throw new Error('Action with op="set" requires a "field" property (e.g., "category", "payee", "notes", "cleared")');
-            }
-            // Validate action field values for ID-type fields
-            if (action.op === 'set' && action.field) {
-                // Check if using category field with text value instead of ID
-                if (action.field === 'category' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Action field "category" expects a category ID (UUID), but got text value "${action.value}". ` +
-                        `Use the category UUID from your budget data. You can list categories to find the correct UUID.`);
-                }
-                // Check if using payee field with text value instead of ID
-                if (action.field === 'payee' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Action field "payee" expects a payee ID (UUID), but got text value "${action.value}". ` +
-                        `Use the payee UUID from your budget data. You can list payees to find the correct UUID.`);
-                }
-                // Check if using account field with text value instead of ID
-                if (action.field === 'account' && typeof action.value === 'string' && !action.value.match(/^[0-9a-f-]{36}$/i)) {
-                    throw new Error(`Action field "account" expects an account ID (UUID), but got text value "${action.value}". ` +
-                        `Use the account UUID from your budget data. You can list accounts to find the correct UUID.`);
-                }
-            }
-            // Validate append-notes and prepend-notes have string values
-            if ((action.op === 'append-notes' || action.op === 'prepend-notes') && typeof action.value !== 'string') {
-                throw new Error(`Action "${action.op}" requires a string value, but got ${typeof action.value}. ` +
-                    `Example: {op: "${action.op}", value: "text to ${action.op === 'append-notes' ? 'append' : 'prepend'}"}`);
-            }
-        }
-        // Validate field usage to guide users toward correct field selection
-        for (const condition of input.conditions) {
-            const fieldInfo = FIELD_OPERATORS[condition.field];
-            // Validate operator is compatible with field type
-            if (fieldInfo && !fieldInfo.operators.includes(condition.op)) {
-                throw new Error(`Invalid operator "${condition.op}" for field "${condition.field}". ` +
-                    `Field "${condition.field}" is a ${fieldInfo.type} field and only supports: ${fieldInfo.operators.join(', ')}. ` +
-                    `Please use one of these operators instead.`);
-            }
-            // Check if using payee field with text value instead of ID
-            if (condition.field === 'payee' && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                throw new Error(`Field "payee" expects a payee ID (UUID), but got text value "${condition.value}". ` +
-                    `To match payee names with text, use "imported_payee" field instead. ` +
-                    `Example: {field: "imported_payee", op: "contains", value: "${condition.value}"}`);
-            }
-            // Similar validation for account and category
-            if (['account', 'category'].includes(condition.field) && typeof condition.value === 'string' && !condition.value.match(/^[0-9a-f-]{36}$/i)) {
-                throw new Error(`Field "${condition.field}" expects an ID (UUID), but got text value "${condition.value}". ` +
-                    `Use the ${condition.field} UUID from your budget data. List ${condition.field === 'account' ? 'accounts' : 'categories'} to find the correct UUID.`);
-            }
-            // Validate oneOf/notOneOf operators expect array values
-            if (['oneOf', 'notOneOf'].includes(condition.op) && !Array.isArray(condition.value)) {
-                throw new Error(`Operator "${condition.op}" expects an array of values, but got ${typeof condition.value}. ` +
-                    `Example: {field: "${condition.field}", op: "${condition.op}", value: ["uuid-1", "uuid-2"]}`);
-            }
-        }
+        const input = RuleItemSchema.parse(args || {});
+        validateRuleInput(input);
         // No automatic translation - require explicit field names
         const ruleData = JSON.parse(JSON.stringify(input)); // deep clone
         const ruleId = await adapter.createRule(ruleData);

package/dist/src/tools/rules_create_batch.js

@@ -0,0 +1,47 @@
+import { z } from 'zod';
+import { createTool } from '../lib/toolFactory.js';
+import { RuleItemSchema, validateRuleInput } from '../lib/schemas/rules.js';
+import adapter from '../lib/actual-adapter.js';
+const InputSchema = z.object({
+    rules: z.array(RuleItemSchema).min(1).max(50)
+        .describe('1 to 50 rules, each exactly the input of actual_rules_create'),
+});
+// createTool() wraps the return value as { result }. The whole array is shape-validated
+// before anything is written (a Zod error refuses the call). The per-rule checks of
+// actual_rules_create (validateRuleInput) are per item: a failing rule goes to `failed` and
+// the rest continue. Only passing items reach the adapter, with their ORIGINAL indices.
+export default createTool({
+    name: 'actual_rules_create_batch',
+    description: `Create 1 to 50 budget rules in one call, each exactly the input of actual_rules_create.
+
+NOT atomic and no rollback: each rule is created independently, and rules created before a failure stay created. A rule that fails its own checks, names a category, payee or account id that does not exist, or is rejected by Actual is reported in "failed" with its index, and the rest are still attempted. Ids in link-schedule actions are not checked. A create is never retried automatically.
+
+If the call itself fails (timeout, lost connection), or an item says "not attempted", read the rules back with actual_rules_get BEFORE retrying ANY item: items marked "not attempted" were never sent, but others may have been created.
+
+Returns: { succeeded: [{index, id}], failed: [{index, error}], total, successCount, failureCount }. Every rule failing is a normal result (successCount 0), not a tool error.`,
+    schema: InputSchema,
+    handler: async (input) => {
+        const total = input.rules.length;
+        const failed = [];
+        const pass = [];
+        input.rules.forEach((rule, index) => {
+            try {
+                validateRuleInput(rule);
+                pass.push({ index, rule: JSON.parse(JSON.stringify(rule)) });
+            }
+            catch (error) {
+                failed.push({ index, error: error instanceof Error ? error.message : String(error) });
+            }
+        });
+        // If no item passes, no queued op runs. A whole-call failure propagates as a tool error.
+        let succeeded = [];
+        if (pass.length > 0) {
+            const res = await adapter.createRulesBatch(pass, total);
+            succeeded = res.succeeded;
+            failed.push(...res.failed);
+        }
+        failed.sort((a, b) => a.index - b.index);
+        succeeded.sort((a, b) => a.index - b.index);
+        return { succeeded, failed, total, successCount: succeeded.length, failureCount: failed.length };
+    },
+});

package/dist/src/tools/rules_create_or_update.js

@@ -24,26 +24,15 @@
  */
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
-// Mirrors the same schemas used in rules_create.ts
-const ConditionSchema = z.object({
-    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category", "imported_payee")'),
-    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
-    value: z.union([z.string(), z.number()]).describe('Value to match against'),
-    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
-});
+import { ACTION_DESCRIBE, CONDITION_OPERATORS_HELP, ConditionSchema, STAGE_DESCRIBE } from '../lib/schemas/rules.js';
+// #486: the condition schema is the shared one; the action schema stays private (same shape as
+// the shared one) and only borrows the describe text.
 const ActionSchema = z.object({
-    op: z.string()
-        .default('set')
-        .describe('Operation to perform. Options: "set" (default), "set-split-amount", "link-schedule", "prepend-notes", "append-notes"'),
-    field: z.string()
-        .optional()
-        .describe('Field to modify — required for "set" op. Options: "category", "payee", "notes", "cleared", "account"'),
-    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()])
-        .describe('Value to assign. Use UUIDs for id-type fields, text for strings, numbers for amounts'),
-    type: z.string()
-        .optional()
-        .describe('Value type hint: "id", "string", "number", "boolean"'),
-    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
+    op: z.string().default('set').describe(`${ACTION_DESCRIBE.op}. Default "set"`),
+    field: z.string().optional().describe(ACTION_DESCRIBE.field),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()]).describe(ACTION_DESCRIBE.value),
+    type: z.string().optional().describe(ACTION_DESCRIBE.type),
+    options: z.object({}).passthrough().optional().describe(ACTION_DESCRIBE.options),
 });
 // Same operator validation map as rules_create.ts
 const FIELD_OPERATORS = {
@@ -66,31 +55,20 @@ const InputSchema = z.object({
         .enum(['pre', 'post'])
         .nullable()
         .optional()
-        .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
-        '"pre" runs before it, "post" after. On an update, omitting this leaves the existing stage unchanged.'),
-    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine multiple conditions'),
-    conditions: z.array(ConditionSchema).describe('Array of conditions that must be met'),
-    actions: z.array(ActionSchema).describe('Array of actions to perform when conditions match'),
+        .describe(`${STAGE_DESCRIBE}. On an update, omitting this leaves the existing stage unchanged`),
+    conditionsOp: z.enum(['and', 'or']).optional().default('and').describe('How to combine conditions'),
+    conditions: z.array(ConditionSchema).describe('Conditions that must be met'),
+    actions: z.array(ActionSchema).describe('Actions to perform when they are met'),
 });
 const tool = {
     name: 'actual_rules_create_or_update',
-    description: `Create a rule if no matching rule exists, or update the existing rule if one with the same conditions already exists. Prevents duplicate rules.
-
-Matching logic: a rule is considered a "match" when it has the same set of conditions (field + op + value triples) and the same conditionsOp ("and"/"or"). Condition order is irrelevant.
+    description: `Create a rule, or update the existing rule with the same conditions. Prevents duplicates.
 
-When a match is found: the rule's actions are REPLACED with the new values. The stage is replaced ONLY if you
-supply one; omit stage to leave the matched rule in whatever stage it is already in. On a newly created rule,
-an omitted stage means the normal stage (null), the same one the UI assigns.
-When no match exists: a new rule is created.
+A rule matches when it has the same conditions (field, op, value) and conditionsOp, in any order. On a match the rule's actions are REPLACED, and its stage is replaced ONLY if you supply one (omit stage to leave it). A newly created rule with no stage gets the normal stage (null).
 
-IMPORTANT Field Types:
-- "imported_payee" (string) — text matching. Supports: contains, matches, doesNotContain, is, isNot
-- "payee" (ID) — exact payee UUID. Supports: is, isNot, oneOf, notOneOf
-- "account", "category" (ID) — UUID matching. Supports: is, isNot, oneOf, notOneOf
-- "notes", "description" (string) — text matching. Supports: contains, matches, doesNotContain, is, isNot
-- "amount", "date" (number/date) — supports: is, gte, lte, gt, lt
+${CONDITION_OPERATORS_HELP}
 
-Returns: { id, created: boolean } — created=true if new rule was created, false if existing rule was updated.`,
+Returns: { id, created: boolean }, created=true for a new rule, false for an updated one.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         // Zod validation errors are formatted centrally by actualToolsManager (#206).

package/dist/src/tools/rules_update.js

@@ -1,19 +1,15 @@
 import { z } from 'zod';
 import adapter from '../lib/actual-adapter.js';
 import { CommonSchemas } from '../lib/schemas/common.js';
-// Define the schema for rule conditions and actions (same as create)
-const ConditionSchema = z.object({
-    field: z.string().describe('Field to match (e.g., "payee", "notes", "amount", "category")'),
-    op: z.string().describe('Operation (e.g., "is", "contains", "isapprox", "gte", "lte")'),
-    value: z.union([z.string(), z.number()]).describe('Value to match against'),
-    type: z.string().optional().describe('Type of condition (e.g., "string", "number", "id")'),
-});
+import { ACTION_DESCRIBE, CONDITION_OPERATORS_HELP, ConditionSchema, STAGE_DESCRIBE } from '../lib/schemas/rules.js';
+// #486: the condition schema is the shared one. The action schema stays private because `op`
+// is REQUIRED here (the shared one defaults it to "set"); only the describe text is shared.
 const ActionSchema = z.object({
-    op: z.string().describe('Operation to perform (e.g., "set", "set-split-amount", "link-schedule", "prepend-notes", "append-notes")'),
-    field: z.string().optional().describe('Field to set (e.g., "category", "payee", "notes", "cleared") - required for "set" operation'),
-    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()]).describe('Value to set or use in operation'),
-    type: z.string().optional().describe('Type of action (e.g., "id", "string", "number", "boolean")'),
-    options: z.object({}).passthrough().optional().describe('Additional options for the action'),
+    op: z.string().describe(ACTION_DESCRIBE.op),
+    field: z.string().optional().describe(ACTION_DESCRIBE.field),
+    value: z.union([z.string(), z.number(), z.boolean(), z.object({}).passthrough()]).describe(ACTION_DESCRIBE.value),
+    type: z.string().optional().describe(ACTION_DESCRIBE.type),
+    options: z.object({}).passthrough().optional().describe(ACTION_DESCRIBE.options),
 });
 // Operator validation map
 const FIELD_OPERATORS = {
@@ -38,30 +34,18 @@ const InputSchema = z.object({
             .enum(['pre', 'post'])
             .nullable()
             .optional()
-            .describe('When to apply the rule. null is Actual\'s normal stage (what the UI gives a rule with no stage chosen); ' +
-            '"pre" runs before it, "post" after. Omit to leave the rule\'s current stage unchanged.'),
-        conditionsOp: z.enum(['and', 'or']).optional().describe('How to combine multiple conditions'),
-        conditions: z.array(ConditionSchema).optional().describe('New array of conditions'),
-        actions: z.array(ActionSchema).optional().describe('New array of actions'),
+            .describe(`${STAGE_DESCRIBE}. Omit to leave the rule's current stage unchanged`),
+        conditionsOp: z.enum(['and', 'or']).optional().describe('How to combine conditions'),
+        conditions: z.array(ConditionSchema).optional().describe('New conditions'),
+        actions: z.array(ActionSchema).optional().describe('New actions'),
     }).describe('Fields to update'),
 });
 const tool = {
     name: 'actual_rules_update',
-    description: `Update an existing budget rule by ID. Only provide the fields you want to change.
-
-IMPORTANT Field Types:
-- "imported_payee" (string) - for text matching payee names. Supports: contains, matches, doesNotContain, is, isNot
-- "payee" (ID) - for exact payee ID matching. Supports: is, isNot, oneOf, notOneOf
-- "account", "category" (ID) - for account/category IDs. Supports: is, isNot, oneOf, notOneOf
-- "notes", "description" (string) - for text matching. Supports: contains, matches, doesNotContain, is, isNot
-- "amount", "date" (number/date) - supports: is, gte, lte, gt, lt
-
-Stage: omit it to leave the rule where it is. Pass null to move it to the normal stage (where UI-created
-rules live), 'pre' to run before that stage, or 'post' to run after. Do NOT pass "default" as a string;
-Actual rejects it.
-Action operators: 'set', 'set-split-amount', 'link-schedule', 'append-notes'.
+    description: `Update an existing budget rule by ID. Only provide the fields you want to change; do not repeat the rule ID inside fields.
 
-Do not include the rule ID in the fields object - it is provided separately.`,
+${CONDITION_OPERATORS_HELP}
+Stage: omit it to leave the rule where it is, pass null for the normal stage, or 'pre' / 'post'. Do NOT pass "default"; Actual rejects it.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});

package/dist/src/tools/schedules_create.js

@@ -4,27 +4,27 @@ import { CommonSchemas } from '../lib/schemas/common.js';
 import { RecurConfigSchema } from '../lib/schemas/recur.js';
 const InputSchema = z.object({
     name: z.string().optional()
-        .describe('Unique display name for the schedule'),
+        .describe('Unique display name'),
     payee: CommonSchemas.payeeId.optional()
-        .describe('Payee UUID (from actual_payees_get)'),
+        .describe('Payee UUID'),
     account: CommonSchemas.accountId.optional()
-        .describe('Account UUID (from actual_accounts_list). If omitted the schedule is not tied to an account'),
+        .describe('Account UUID. If omitted the schedule is not tied to an account'),
     amount: z.number().int().optional()
-        .describe('Amount in cents. Negative = expense (e.g. -5000 = -$50.00), positive = income'),
+        .describe('Amount in cents, negative = expense'),
     amountOp: z.enum(['is', 'isapprox', 'isbetween']).optional().default('is')
-        .describe('How to match the amount. "isbetween" requires amount to be an object { num1, num2 }'),
+        .describe('How to match the amount'),
     date: z.union([
         z.string().regex(/^\d{4}-\d{2}-\d{2}$/)
-            .describe('YYYY-MM-DD — one-off schedule on this specific date'),
+            .describe('One-off schedule on this date'),
         RecurConfigSchema
-            .describe('RecurConfig object — recurring schedule'),
-    ]).describe('Date string for one-off or RecurConfig object for recurring. Required.'),
+            .describe('Recurring schedule'),
+    ]).describe('YYYY-MM-DD for one-off, RecurConfig object for recurring. Required.'),
     posts_transaction: z.boolean().optional().default(false)
-        .describe('When true, Actual automatically posts a transaction on each occurrence'),
+        .describe('Auto-post a transaction on each occurrence'),
 });
 const tool = {
     name: 'actual_schedules_create',
-    description: `Create a new schedule in Actual Budget. Schedules can be one-off (supply a YYYY-MM-DD date string) or recurring (supply a RecurConfig object with frequency, start, and endMode). Amounts are in cents — negative for expenses, positive for income.`,
+    description: `Create a schedule, one-off (YYYY-MM-DD date) or recurring (RecurConfig object with frequency, start, endMode). Amounts are in cents, negative for expenses.`,
     inputSchema: InputSchema,
     call: async (args, _meta) => {
         const input = InputSchema.parse(args || {});