@dizzlkheinz/ynab-mcpb 0.12.1

package/docs/reference/API.md

@@ -0,0 +1,1450 @@
+# YNAB MCP Server API Reference
+
+This document provides comprehensive documentation for all tools available in the YNAB MCP Server, including parameters, examples, and error handling.
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Authentication](#authentication)
+- [Data Formats](#data-formats)
+- [Budget Management Tools](#budget-management-tools)
+- [Account Management Tools](#account-management-tools)
+- [Transaction Management Tools](#transaction-management-tools)
+- [Category Management Tools](#category-management-tools)
+- [Payee Management Tools](#payee-management-tools)
+- [Monthly Data Tools](#monthly-data-tools)
+- [Utility Tools](#utility-tools)
+- [Diagnostic Tools](#diagnostic-tools)
+- [Error Handling](#error-handling)
+
+## Overview
+
+The YNAB MCP Server provides 30 tools that enable AI assistants to interact with YNAB data. All tools follow consistent patterns for parameters, responses, and error handling.
+
+### Tool Naming Convention
+
+All tools follow a simple naming pattern with an action and resource:
+- `list_budgets` - List operation on budgets
+- `get_budget` - Get operation on a specific budget
+- `create_transaction` - Create operation for transactions
+
+## Authentication
+
+All tools require authentication via a YNAB Personal Access Token set in the `YNAB_ACCESS_TOKEN` environment variable.
+
+```bash
+YNAB_ACCESS_TOKEN=your_personal_access_token_here
+```
+
+## Data Formats
+
+### Monetary Amounts
+
+**📢 New in v0.7.0**: All monetary amounts are automatically converted to standard dollar format for human readability.
+
+The server automatically converts YNAB's internal milliunits to dollars in all responses:
+- Account balances: `-1924.37` (instead of `-1924370` milliunits)
+- Transaction amounts: `50.25` (instead of `50250` milliunits)
+- Budget amounts: `150.00` (instead of `150000` milliunits)
+
+**Input formats**:
+- When creating transactions, amounts should be provided in milliunits (as per YNAB API requirements)
+- Use the `convert_amount` tool to convert between dollars and milliunits if needed
+
+**Legacy behavior**: YNAB's internal representation uses milliunits (1/1000th of currency unit), but this is now transparent to users
+
+### Dates
+
+All dates use ISO 8601 format: `YYYY-MM-DD`
+- Example: `2024-01-15`
+- Time zones are handled by YNAB based on your account settings
+
+### IDs
+
+All YNAB IDs are UUID strings:
+- Budget ID: `12345678-1234-1234-1234-123456789012`
+- Account ID: `87654321-4321-4321-4321-210987654321`
+
+## Budget Management Tools
+
+### list_budgets
+
+Lists all budgets associated with the user's account.
+
+**Parameters:** None
+
+**Example Request:**
+```json
+{
+  "name": "list_budgets",
+  "arguments": {}
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"budgets\": [\n    {\n      \"id\": \"12345678-1234-1234-1234-123456789012\",\n      \"name\": \"My Budget\",\n      \"last_modified_on\": \"2024-01-15T10:30:00.000Z\",\n      \"first_month\": \"2024-01-01\",\n      \"last_month\": \"2024-12-01\",\n      \"date_format\": {\n        \"format\": \"MM/DD/YYYY\"\n      },\n      \"currency_format\": {\n        \"iso_code\": \"USD\",\n        \"example_format\": \"123,456.78\",\n        \"decimal_digits\": 2,\n        \"decimal_separator\": \".\",\n        \"symbol_first\": true,\n        \"group_separator\": \",\",\n        \"currency_symbol\": \"$\",\n        \"display_symbol\": true\n      }\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+### get_budget
+
+Gets detailed information for a specific budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget to retrieve
+
+**Example Request:**
+```json
+{
+  "name": "get_budget",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012"
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"budget\": {\n    \"id\": \"12345678-1234-1234-1234-123456789012\",\n    \"name\": \"My Budget\",\n    \"last_modified_on\": \"2024-01-15T10:30:00.000Z\",\n    \"first_month\": \"2024-01-01\",\n    \"last_month\": \"2024-12-01\",\n    \"accounts\": [...],\n    \"payees\": [...],\n    \"payee_locations\": [...],\n    \"category_groups\": [...],\n    \"categories\": [...],\n    \"months\": [...],\n    \"transactions\": [...],\n    \"subtransactions\": [...],\n    \"scheduled_transactions\": [...],\n    \"scheduled_subtransactions\": [...]\n  }\n}"
+    }
+  ]
+}
+```
+
+## Account Management Tools
+
+### list_accounts
+
+Lists all accounts for a specific budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+
+**Example Request:**
+```json
+{
+  "name": "list_accounts",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012"
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"accounts\": [\n    {\n      \"id\": \"87654321-4321-4321-4321-210987654321\",\n      \"name\": \"Checking Account\",\n      \"type\": \"checking\",\n      \"on_budget\": true,\n      \"closed\": false,\n      \"note\": null,\n      \"balance\": 150000,\n      \"cleared_balance\": 145000,\n      \"uncleared_balance\": 5000,\n      \"transfer_payee_id\": \"transfer-payee-id\",\n      \"direct_import_linked\": false,\n      \"direct_import_in_error\": false,\n      \"last_reconciled_at\": null,\n      \"debt_original_balance\": null,\n      \"debt_interest_rates\": {},\n      \"debt_minimum_payments\": {},\n      \"debt_escrow_amounts\": {}\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+### get_account
+
+Gets detailed information for a specific account.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `account_id` (string, required): The ID of the account
+
+**Example Request:**
+```json
+{
+  "name": "get_account",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321"
+  }
+}
+```
+
+### create_account
+
+Creates a new account in the specified budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `name` (string, required): The name of the new account
+- `type` (string, required): The account type. Valid values:
+  - `checking` - Checking account
+  - `savings` - Savings account
+  - `creditCard` - Credit card account
+  - `cash` - Cash account
+  - `lineOfCredit` - Line of credit
+  - `otherAsset` - Other asset account
+  - `otherLiability` - Other liability account
+- `balance` (number, optional): Initial balance in milliunits
+- `dry_run` (boolean, optional): Validate and return simulated result; no API call
+
+**Example Request:**
+```json
+{
+  "name": "create_account",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "name": "New Savings Account",
+    "type": "savings",
+    "balance": 100000
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"account\": {\n    \"id\": \"new-account-id\",\n    \"name\": \"New Savings Account\",\n    \"type\": \"savings\",\n    \"on_budget\": true,\n    \"closed\": false,\n    \"balance\": 100000,\n    \"cleared_balance\": 100000,\n    \"uncleared_balance\": 0\n  }\n}"
+    }
+  ]
+}
+```
+
+## Transaction Management Tools
+
+### list_transactions
+
+Lists transactions for a budget with optional filtering.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `account_id` (string, optional): Filter by account ID
+- `category_id` (string, optional): Filter by category ID
+- `since_date` (string, optional): Only return transactions on or after this date (YYYY-MM-DD)
+- `type` (string, optional): Filter by transaction type (`uncategorized` or `unapproved`)
+
+**Example Request:**
+```json
+{
+  "name": "list_transactions",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "since_date": "2024-01-01"
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5000,\n      \"memo\": \"Coffee shop\",\n      \"cleared\": \"cleared\",\n      \"approved\": true,\n      \"flag_color\": null,\n      \"account_id\": \"87654321-4321-4321-4321-210987654321\",\n      \"payee_id\": \"payee-id\",\n      \"category_id\": \"category-id\",\n      \"transfer_account_id\": null,\n      \"transfer_transaction_id\": null,\n      \"matched_transaction_id\": null,\n      \"import_id\": null,\n      \"import_payee_name\": null,\n      \"import_payee_name_original\": null,\n      \"debt_transaction_type\": null,\n      \"deleted\": false\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+### export_transactions
+
+Exports all transactions to a JSON file with descriptive filename and platform-specific default paths. This tool bypasses MCP response size limits by saving data to a file instead of returning it in the response.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `account_id` (string, optional): Filter by account ID
+- `category_id` (string, optional): Filter by category ID
+- `since_date` (string, optional): Only export transactions on or after this date (YYYY-MM-DD)
+- `type` (string, optional): Filter by transaction type (`uncategorized` or `unapproved`)
+- `filename` (string, optional): Custom filename (auto-generated if not provided)
+- `minimal` (boolean, optional): Export only essential fields for smaller files (default: true)
+
+**Example Request:**
+```json
+{
+  "name": "export_transactions",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "since_date": "2024-01-01"
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"message\": \"Successfully exported 1247 transactions\",\n  \"filename\": \"ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"full_path\": \"C:\\\\Users\\\\YourName\\\\Downloads\\\\ynab_since_2024-01-01_1247items_2024-09-10_14-30-15.json\",\n  \"export_directory\": \"C:\\\\Users\\\\YourName\\\\Downloads\",\n  \"filename_explanation\": \"Filename format: ynab_{filters}_{count}items_{timestamp}.json - identifies what data was exported, when, and how many transactions\",\n  \"preview_count\": 10,\n  \"total_count\": 1247,\n  \"preview_transactions\": [\n    {\n      \"id\": \"transaction-id\",\n      \"date\": \"2024-01-15\",\n      \"amount\": -5000,\n      \"memo\": \"Coffee shop\",\n      \"payee_name\": \"Starbucks\",\n      \"category_name\": \"Dining Out\"\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+**Export File Structure:**
+The exported JSON file contains:
+- `export_info`: Metadata about the export (timestamp, filters, count, minimal flag)
+- `transactions`: Array of transaction objects
+  - **Minimal mode (default)**: `id`, `date`, `amount`, `payee_name`, `cleared`
+  - **Full mode**: All available transaction fields
+
+**Platform-Specific Default Paths:**
+- Windows/Mac: `~/Downloads`
+- Linux/Unix: `~/Documents` (or `$XDG_DOCUMENTS_DIR`)
+- Configurable via `YNAB_EXPORT_PATH` environment variable
+
+### compare_transactions
+
+Compares bank transactions from CSV files with YNAB transactions to identify missing entries in either direction. This tool helps with bank statement reconciliation by finding transactions that exist in your bank statement but not in YNAB (need to import) or vice versa (double-check for duplicates).
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget to compare against
+- `account_id` (string, required): The ID of the account to compare transactions for
+- `csv_file_path` (string, optional): Path to CSV file containing bank transactions
+- `csv_data` (string, optional): CSV data as string (alternative to csv_file_path)
+- `amount_tolerance` (number, optional): Amount difference tolerance as decimal (0.01 = 1%, default: 0.01)
+- `date_tolerance_days` (number, optional): Date difference tolerance in days (default: 5)
+- `csv_format` (object, optional): CSV format configuration
+  - `date_column` (string): Column name for transaction date when `has_header: true`, or column index as string when `has_header: false` (default: "Date")
+  - `amount_column` (string): Column name for transaction amount when `has_header: true`, or column index as string when `has_header: false` (default: "Amount")
+  - `description_column` (string): Column name for transaction description when `has_header: true`, or column index as string when `has_header: false` (default: "Description")
+  - `date_format` (string): Date format pattern (default: "MM/DD/YYYY")
+  - `has_header` (boolean): Whether CSV has header row (default: true)
+  - `delimiter` (string): CSV delimiter character (default: ",")
+
+**Example Request (CSV data):**
+```json
+{
+  "name": "compare_transactions",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "csv_data": "Date,Amount,Description\n2024-01-01,100.00,Coffee Shop\n2024-01-02,-50.25,Gas Station\n2024-01-03,25.00,ATM Withdrawal"
+  }
+}
+```
+
+**Example Request (CSV file with custom format):**
+```json
+{
+  "name": "compare_transactions",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "csv_file_path": "/path/to/bank-statement.csv",
+    "csv_format": {
+      "date_column": "Transaction Date",
+      "amount_column": "Dollar Amount",
+      "description_column": "Description",
+      "date_format": "DD/MM/YYYY",
+      "delimiter": ";",
+      "has_header": true
+    },
+    "amount_tolerance": 0.02,
+    "date_tolerance_days": 3
+  }
+}
+```
+
+**Example Request (CSV without headers using column indices):**
+```json
+{
+  "name": "compare_transactions",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "csv_data": "2024-01-01,100.00,Coffee Shop\n2024-01-02,-15.50,ATM Fee\n2024-01-03,250.00,Paycheck",
+    "csv_format": {
+      "date_column": "0",
+      "amount_column": "1",
+      "description_column": "2",
+      "date_format": "YYYY-MM-DD",
+      "has_header": false,
+      "delimiter": ","
+    }
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"summary\": {\n    \"bank_transactions_count\": 15,\n    \"ynab_transactions_count\": 12,\n    \"matches_found\": 10,\n    \"missing_in_ynab\": 5,\n    \"missing_in_bank\": 2,\n    \"date_range\": {\n      \"start\": \"2024-01-01\",\n      \"end\": \"2024-01-15\"\n    },\n    \"parameters\": {\n      \"amount_tolerance\": 0.01,\n      \"date_tolerance_days\": 5\n    }\n  },\n  \"matches\": [\n    {\n      \"bank_date\": \"2024-01-01\",\n      \"bank_amount\": \"100.00\",\n      \"bank_description\": \"Coffee Shop\",\n      \"ynab_date\": \"2024-01-01\",\n      \"ynab_amount\": \"100.00\",\n      \"ynab_payee\": \"Starbucks\",\n      \"match_score\": 90,\n      \"match_reasons\": [\"Exact date match\", \"Exact amount match\"]\n    }\n  ],\n  \"missing_in_ynab\": [\n    {\n      \"date\": \"2024-01-03\",\n      \"amount\": \"25.00\",\n      \"description\": \"ATM Withdrawal\",\n      \"row_number\": 4\n    }\n  ],\n  \"missing_in_bank\": [\n    {\n      \"id\": \"transaction-xyz\",\n      \"date\": \"2024-01-02\",\n      \"amount\": \"-15.50\",\n      \"payee_name\": \"Coffee Bean\",\n      \"memo\": \"Morning coffee\",\n      \"cleared\": \"cleared\"\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+**Matching Algorithm:**
+- **Date matching** (40 points max): Exact dates get full points, nearby dates get partial points
+- **Amount matching** (50 points max): Exact amounts get full points, close amounts within tolerance get partial points
+- **Description matching** (10 points max): Similarity between bank description and YNAB payee/memo
+- **Smart Duplicate Handling**: Multiple transactions with identical amounts are matched using chronological order with chronology bonus (+15 points for same day, +10 for within 3 days)
+- **Minimum match score**: 30 points required for a valid match
+
+**Supported Date Formats:**
+- `MM/DD/YYYY` or `M/D/YYYY` (default)
+- `DD/MM/YYYY` or `D/M/YYYY`
+- `YYYY-MM-DD` (ISO format)
+- `MM-DD-YYYY`
+
+**Use Cases:**
+- **Bank reconciliation**: Find transactions missing from YNAB that need to be imported
+- **Duplicate detection**: Identify YNAB transactions that don't appear in bank statements
+- **Import verification**: Verify that imported transactions match your bank statement exactly
+- **Data cleanup**: Find and resolve discrepancies between bank and YNAB data
+
+### reconcile_account
+
+Performs comprehensive account reconciliation with bank statement data. The tool returns **two content entries**: a human-readable narrative for assistants and a structured JSON payload (`version: "2.0"`) that encodes MoneyValue objects, insights, and optional execution results.
+
+**Parameters (selected):**
+- `budget_id` / `account_id` (string, required)
+- `csv_file_path` or `csv_data` (one required)
+- `statement_balance` (number, required) – ending cleared balance from the statement in dollars
+- `statement_start_date`, `statement_end_date`, `statement_date` (string, optional)
+- Matching controls: `date_tolerance_days` (default 2), `amount_tolerance_cents` (default 1), `auto_match_threshold` (default 90), `suggestion_threshold` (default 60)
+- Execution controls (optional):
+  - `auto_create_transactions` (default `false`)
+  - `auto_update_cleared_status` (default `false`)
+  - `auto_unclear_missing` (default `true`)
+  - `auto_adjust_dates` (default `false`)
+  - `dry_run` (default `true`)
+  - `amount_tolerance` (deprecated decimal fallback – automatically inferred from `amount_tolerance_cents`)
+- Other legacy options remain accepted for compatibility (`expected_bank_balance`, `balance_verification_mode`, `require_exact_match`, etc.).
+
+**Example Request:**
+```json
+{
+  "name": "reconcile_account",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "csv_data": "Date,Description,Amount\n2025-10-20,Amazon,-23.47\n2025-10-22,Coffee Shop,-4.50\n2025-10-23,Grocery Store,-67.89",
+    "statement_balance": -560.38,
+    "statement_start_date": "2025-10-01",
+    "statement_end_date": "2025-10-31",
+    "auto_create_transactions": true,
+    "dry_run": true
+  }
+}
+```
+
+**Example Response (truncated):**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "📊 Checking Account Reconciliation Report\nStatement Range: 2025-10-01 to 2025-10-31\n\n• YNAB Cleared Balance: -$899.02\n• Statement Balance: -$921.24\n❌ Discrepancy: $22.22 (Statement shows more owed than YNAB)\n\nMatches: 5 auto, 1 suggested, 1 unmatched bank, 0 unmatched YNAB\n\nInsights:\n• [WARNING] 1 unmatched transaction at $22.22\n\nNext Steps:\n• Review 5 auto-matched transactions for approval\n• Add missing bank transaction\n\nDry run only — no YNAB changes were applied."
+    },
+    {
+      "type": "text",
+      "text": "{\n  \"version\": \"2.0\",\n  \"schema_url\": \"https://raw.githubusercontent.com/dizzlkheinz/ynab-mcp-mcpb/master/docs/schemas/reconciliation-v2.json\",\n  \"summary\": {\n    \"bank_transactions_count\": 7,\n    \"auto_matched\": 5,\n    \"current_cleared_balance\": {\n      \"value_milliunits\": -899020,\n      \"value_display\": \"-$899.02\",\n      \"currency\": \"USD\",\n      \"direction\": \"debit\"\n    },\n    \"discrepancy\": {\n      \"value_display\": \"$22.22\"\n    }\n  },\n  \"balance\": {\n    \"discrepancy_direction\": \"bank_higher\"\n  },\n  \"csv_format\": {\n    \"delimiter\": \",\",\n    \"decimal_separator\": \".\",\n    \"thousands_separator\": null,\n    \"date_format\": \"MM/DD/YYYY\",\n    \"header_row\": true,\n    \"date_column\": \"Date\",\n    \"amount_column\": \"Amount\",\n    \"payee_column\": \"Description\"\n  },\n  \"insights\": [ { \"id\": \"repeat-22.22\", \"type\": \"repeat_amount\" } ],\n  \"matches\": { ... },\n  \"unmatched\": { ... },\n  \"execution\": {\n    \"summary\": {\n      \"matches_found\": 6,\n      \"transactions_created\": 1,\n      \"transactions_updated\": 2,\n      \"dry_run\": false\n    },\n    \"account_balance\": {\n      \"before\": { \"cleared_balance\": { \"value_display\": \"-$899.02\" }, ... },\n      \"after\": { \"cleared_balance\": { \"value_display\": \"-$921.24\" }, ... }\n    },\n    \"recommendations\": [\"Review EvoCarShare discrepancy\"]\n  }\n}"
+    }
+  ]
+}
+```
+
+When execution flags are enabled and `dry_run` is `false`, the structured payload includes an `execution` block with created/updated transactions, recommendations, and MoneyValue snapshots. The human narrative also summarizes applied actions.
+
+**Key Output Sections:**
+- `summary` – counts and MoneyValue balances for the statement window
+- `balance` – MoneyValue snapshots plus discrepancy direction (`bank_higher`, `ynab_higher`, or `balanced`)
+- `insights` – repeat-amount, near-match, and anomaly callouts with evidence
+- `next_steps` – ordered suggestions for assistants to surface
+- `matches`, `unmatched` – detailed transaction lists with MoneyValue fields for amounts
+- `execution` (optional) – action totals, recommendations, and balance reconciliation metrics (MoneyValue)
+- `recommendations` (optional) – actionable suggestions with complete parameters for executing YNAB tool calls
+
+### Recommendations Field
+
+The `reconcile_account_v2` tool now includes an optional `recommendations` array with actionable suggestions for resolving discrepancies.
+
+#### Recommendation Types
+
+**Create Transaction**
+```json
+{
+  "id": "rec-123",
+  "action_type": "create_transaction",
+  "priority": "high",
+  "confidence": 0.95,
+  "message": "Create transaction for EvoCarShare",
+  "reason": "This transaction exactly matches your $22.22 discrepancy",
+  "estimated_impact": {
+    "value": 22.22,
+    "value_display": "$22.22",
+    "currency": "USD"
+  },
+  "account_id": "abc123",
+  "parameters": {
+    "account_id": "abc123",
+    "date": "2024-01-15",
+    "amount": 22.22,
+    "payee_name": "EvoCarShare",
+    "memo": "Car rental",
+    "cleared": "cleared",
+    "approved": true
+  }
+}
+```
+
+**Update Cleared Status**
+```json
+{
+  "id": "rec-456",
+  "action_type": "update_cleared",
+  "priority": "low",
+  "confidence": 0.6,
+  "message": "Mark transaction as cleared",
+  "parameters": {
+    "transaction_id": "ynab-txn-789",
+    "cleared": "cleared"
+  }
+}
+```
+
+**Review Duplicate**
+```json
+{
+  "id": "rec-789",
+  "action_type": "review_duplicate",
+  "priority": "medium",
+  "confidence": 0.7,
+  "message": "Review possible duplicate",
+  "parameters": {
+    "candidate_ids": ["ynab-1", "ynab-2"],
+    "suggested_match_id": "ynab-1"
+  }
+}
+```
+
+#### Executing Recommendations
+
+Recommendations include complete parameters for YNAB MCP tool calls:
+
+**CRITICAL**: Recommendation `parameters.amount` values are in **milliunits** (YNAB's internal format where 1 dollar = 1000 milliunits). These values are ready to pass directly to `create_transaction` without conversion. However, `estimated_impact.value` remains in decimal dollars for human readability.
+
+```typescript
+// For create_transaction recommendations:
+// Note: Recommendation amounts are already in milliunits, ready to use directly
+const rec = recommendations.find(r => r.action_type === 'create_transaction');
+if (rec) {
+  await create_transaction({
+    budget_id: 'your-budget-id',
+    ...rec.parameters // Parameters already contain amounts in milliunits
+  });
+}
+
+// For update_cleared recommendations:
+const updateRec = recommendations.find(r => r.action_type === 'update_cleared');
+if (updateRec) {
+  await update_transaction({
+    budget_id: 'your-budget-id',
+    transaction_id: updateRec.parameters.transaction_id,
+    transaction: {
+      cleared: updateRec.parameters.cleared
+    }
+  });
+}
+```
+
+#### Recommendation Priority
+
+- **High**: Exact matches with 90%+ confidence, resolve immediately
+- **Medium**: Likely matches with 60-89% confidence, review before executing
+- **Low**: Suggestions requiring manual review, investigate further
+
+#### Best Practices for Executing Recommendations
+
+**Execution Order**
+
+Process recommendations in the order they're returned (already sorted by priority and confidence):
+
+```typescript
+for (const rec of recommendations) {
+  // High confidence (>0.9) can often be auto-executed
+  if (rec.confidence > 0.9 && rec.action_type === 'create_transaction') {
+    await executeRecommendation(rec);
+  } else {
+    // Lower confidence should be reviewed
+    await reviewAndExecute(rec);
+  }
+}
+```
+
+**Batch Execution**
+
+For multiple recommendations, execute in batches with review checkpoints:
+
+```typescript
+// Group by action type
+const groups = {
+  create: recommendations.filter(r => r.action_type === 'create_transaction'),
+  update: recommendations.filter(r => r.action_type === 'update_cleared'),
+  review: recommendations.filter(r => r.action_type === 'manual_review'),
+};
+
+// Execute high-confidence creates first
+for (const rec of groups.create.filter(r => r.confidence > 0.9)) {
+  await create_transaction({
+    budget_id: budgetId,
+    ...rec.parameters
+  });
+}
+
+// Review checkpoint: verify balance improvement
+const updatedAnalysis = await reconcile_account_v2({ ... });
+console.log('Balance after creates:', updatedAnalysis.balance_info.discrepancy);
+```
+
+**Error Handling and Rollback**
+
+Track executed recommendations for potential rollback:
+
+```typescript
+const executionLog = [];
+
+try {
+  for (const rec of recommendations) {
+    if (rec.action_type === 'create_transaction') {
+      const result = await create_transaction({
+        budget_id: budgetId,
+        ...rec.parameters
+      });
+
+      executionLog.push({
+        recommendation_id: rec.id,
+        transaction_id: result.transaction.id,
+        action: 'create_transaction'
+      });
+    }
+  }
+} catch (error) {
+  // Rollback: delete created transactions
+  for (const log of executionLog.reverse()) {
+    if (log.action === 'create_transaction') {
+      await delete_transaction({
+        budget_id: budgetId,
+        transaction_id: log.transaction_id
+      });
+    }
+  }
+  throw error;
+}
+```
+
+**Verification After Execution**
+
+Always re-run reconciliation after executing recommendations to verify balance improvement:
+
+```typescript
+// Execute recommendations
+await executeRecommendations(recommendations);
+
+// Verify discrepancy resolved
+const verifyAnalysis = await reconcile_account_v2({
+  budget_id: budgetId,
+  account_id: accountId,
+  csv_data: csvData,
+  statement_balance: statementBalance,
+  statement_date: statementDate
+});
+
+const beforeDiscrepancy = originalAnalysis.balance_info.discrepancy.value;
+const afterDiscrepancy = verifyAnalysis.balance_info.discrepancy.value;
+
+if (Math.abs(afterDiscrepancy) >= Math.abs(beforeDiscrepancy)) {
+  console.warn('Discrepancy not improved - review executed recommendations');
+}
+```
+
+**Handling Manual Review Recommendations**
+
+Manual review recommendations require investigation before action:
+
+```typescript
+for (const rec of recommendations.filter(r => r.action_type === 'manual_review')) {
+  console.log(`\n=== ${rec.message} ===`);
+  console.log(`Reason: ${rec.reason}`);
+  console.log(`Issue type: ${rec.parameters.issue_type}`);
+
+  if (rec.parameters.related_transactions) {
+    console.log('\nRelated transactions:');
+    for (const txn of rec.parameters.related_transactions) {
+      console.log(`  - [${txn.source}] ${txn.description} (ID: ${txn.id})`);
+    }
+  }
+
+  // Fetch full details for investigation
+  for (const txn of rec.parameters.related_transactions || []) {
+    if (txn.source === 'ynab') {
+      const details = await get_transaction({
+        budget_id: budgetId,
+        transaction_id: txn.id
+      });
+      console.log(`    Details:`, JSON.stringify(details, null, 2));
+    }
+  }
+}
+```
+
+**Progressive Execution Strategy**
+
+For large discrepancies with many recommendations:
+
+1. **Execute high-confidence creates** (confidence > 0.9, action_type = create_transaction)
+2. **Re-run reconciliation** to verify progress
+3. **Review remaining discrepancy** and adjust strategy
+4. **Process medium-confidence items** with manual review
+5. **Final verification** before marking account as reconciled
+
+### get_transaction
+
+Gets detailed information for a specific transaction.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `transaction_id` (string, required): The ID of the transaction
+
+**Example Request:**
+```json
+{
+  "name": "get_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "transaction_id": "transaction-id"
+  }
+}
+```
+
+### create_transaction
+
+Creates a new transaction in the specified budget and account.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `account_id` (string, required): The ID of the account
+- `amount` (number, required): Transaction amount in milliunits (negative for outflows)
+- `date` (string, required): Transaction date in ISO format (YYYY-MM-DD)
+- `payee_name` (string, optional): The payee name
+- `payee_id` (string, optional): The payee ID
+- `category_id` (string, optional): The category ID
+- `memo` (string, optional): Transaction memo
+- `cleared` (string, optional): Transaction cleared status (`cleared`, `uncleared`, `reconciled`)
+- `approved` (boolean, optional): Whether the transaction is approved
+- `flag_color` (string, optional): Transaction flag color (`red`, `orange`, `yellow`, `green`, `blue`, `purple`)
+- `dry_run` (boolean, optional): Validate and return simulated result; no API call
+- `subtransactions` (array, optional): Split line items; each entry accepts `amount` (milliunits), plus optional `memo`, `category_id`, `payee_id`, and `payee_name`
+
+When `subtransactions` are supplied, their `amount` values must sum to the parent `amount`, matching YNAB API requirements.
+
+**Example Request:**
+```json
+{
+  "name": "create_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "amount": -5000,
+    "date": "2024-01-15",
+    "payee_name": "Coffee Shop",
+    "category_id": "category-id",
+    "memo": "Morning coffee",
+    "cleared": "cleared",
+    "approved": true
+  }
+}
+```
+
+**Split Transaction Example:**
+```json
+{
+  "name": "create_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "amount": -125000,
+    "date": "2024-02-01",
+    "memo": "Rent and utilities",
+    "subtransactions": [
+      { "amount": -100000, "category_id": "rent-category", "memo": "Rent" },
+      { "amount": -25000, "category_id": "utilities-category", "memo": "Utilities" }
+    ]
+  }
+}
+```
+
+### create_receipt_split_transaction
+
+Creates a split transaction from categorized receipt data and allocates taxes proportionally across the selected categories. Use this helper after the user has confirmed the receipt breakdown and category assignments.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `account_id` (string, required): The ID of the account
+- `payee_name` (string, required): Payee to assign to the transaction (e.g., the store name)
+- `date` (string, optional): Transaction date in ISO format (defaults to today when omitted)
+- `memo` (string, optional): Memo applied to the parent transaction
+- `receipt_subtotal` (number, optional): Pre-tax subtotal for validation (calculated automatically if omitted)
+- `receipt_tax` (number, required): Total tax collected on the receipt
+- `receipt_total` (number, required): Final total including tax
+- `categories` (array, required): Categorized line items. Each entry accepts:
+  - `category_id` (string, required)
+  - `category_name` (string, optional, used for tax memo labels)
+  - `items` (array, required): Each item includes `name` (string), `amount` (number), optional `quantity` (number), and optional `memo` (string)
+- `cleared` (string, optional): Cleared status (`cleared`, `uncleared`, `reconciled`). Defaults to `uncleared`
+- `approved` (boolean, optional): Whether the transaction should be marked approved
+- `flag_color` (string, optional): Flag color (`red`, `orange`, `yellow`, `green`, `blue`, `purple`)
+- `dry_run` (boolean, optional): When true, returns a preview without calling YNAB
+
+**Example Request:**
+```json
+{
+  "name": "create_receipt_split_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "account_id": "87654321-4321-4321-4321-210987654321",
+    "payee_name": "IKEA",
+    "date": "2025-10-13",
+    "memo": "Receipt import",
+    "receipt_subtotal": 112.34,
+    "receipt_tax": 11.84,
+    "receipt_total": 124.18,
+    "categories": [
+      {
+        "category_id": "baby-stuff",
+        "category_name": "Baby Stuff",
+        "items": [
+          { "name": "Crib pillow", "amount": 12.99 },
+          { "name": "Bed linen", "amount": 24.99 }
+        ]
+      },
+      {
+        "category_id": "home-maintenance",
+        "category_name": "Home Maintenance",
+        "items": [
+          { "name": "Teapot", "amount": 19.99 },
+          { "name": "Toothbrush holder", "amount": 3.99 }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "transaction": {
+    "id": "new-transaction-456",
+    "amount": -124.18,
+    "payee_name": "IKEA",
+    "cleared": "uncleared",
+    "subtransactions": [
+      { "memo": "Crib pillow", "amount": -12.99, "category_id": "baby-stuff" },
+      { "memo": "Bed linen", "amount": -24.99, "category_id": "baby-stuff" },
+      { "memo": "Tax - Baby Stuff", "amount": -6.11, "category_id": "baby-stuff" },
+      { "memo": "Teapot", "amount": -19.99, "category_id": "home-maintenance" },
+      { "memo": "Toothbrush holder", "amount": -3.99, "category_id": "home-maintenance" },
+      { "memo": "Tax - Home Maintenance", "amount": -5.99, "category_id": "home-maintenance" }
+    ],
+    "account_balance": 2534.87,
+    "account_cleared_balance": 2450.22
+  },
+  "receipt_summary": {
+    "subtotal": 112.34,
+    "tax": 11.84,
+    "total": 124.18,
+    "categories": [
+      {
+        "category_id": "baby-stuff",
+        "category_name": "Baby Stuff",
+        "subtotal": 37.98,
+        "tax": 6.11,
+        "total": 44.09
+      },
+      {
+        "category_id": "home-maintenance",
+        "category_name": "Home Maintenance",
+        "subtotal": 74.36,
+        "tax": 5.73,
+        "total": 80.09
+      }
+    ]
+  }
+}
+```
+
+### update_transaction
+
+Updates an existing transaction.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `transaction_id` (string, required): The ID of the transaction to update
+- `account_id` (string, optional): Update the account ID
+- `amount` (number, optional): Update the amount in milliunits
+- `date` (string, optional): Update the date (YYYY-MM-DD)
+- `payee_name` (string, optional): Update the payee name
+- `payee_id` (string, optional): Update the payee ID
+- `category_id` (string, optional): Update the category ID
+- `memo` (string, optional): Update the memo
+- `cleared` (string, optional): Update the cleared status
+- `approved` (boolean, optional): Update the approved status
+- `flag_color` (string, optional): Update the flag color
+- `dry_run` (boolean, optional): Validate and return simulated result; no API call
+
+**Example Request:**
+```json
+{
+  "name": "update_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "transaction_id": "transaction-id",
+    "amount": -6000,
+    "memo": "Updated memo",
+    "flag_color": "red"
+  }
+}
+```
+
+### delete_transaction
+
+Deletes a transaction from the specified budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `transaction_id` (string, required): The ID of the transaction to delete
+- `dry_run` (boolean, optional): Validate and return simulated result; no API call
+
+**Example Request:**
+```json
+{
+  "name": "delete_transaction",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "transaction_id": "transaction-id"
+  }
+}
+```
+
+## Category Management Tools
+
+### list_categories
+
+Lists all categories for a specific budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+
+**Example Request:**
+```json
+{
+  "name": "list_categories",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012"
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"category_groups\": [\n    {\n      \"id\": \"group-id\",\n      \"name\": \"Monthly Bills\",\n      \"hidden\": false,\n      \"deleted\": false,\n      \"categories\": [\n        {\n          \"id\": \"category-id\",\n          \"category_group_id\": \"group-id\",\n          \"name\": \"Rent/Mortgage\",\n          \"hidden\": false,\n          \"original_category_group_id\": null,\n          \"note\": null,\n          \"budgeted\": 150000,\n          \"activity\": -150000,\n          \"balance\": 0,\n          \"goal_type\": null,\n          \"goal_creation_month\": null,\n          \"goal_target\": null,\n          \"goal_target_month\": null,\n          \"goal_percentage_complete\": null,\n          \"goal_months_to_budget\": null,\n          \"goal_under_funded\": null,\n          \"goal_overall_funded\": null,\n          \"goal_overall_left\": null,\n          \"deleted\": false\n        }\n      ]\n    }\n  ]\n}"
+    }
+  ]
+}
+```
+
+### get_category
+
+Gets detailed information for a specific category.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `category_id` (string, required): The ID of the category
+
+### update_category
+
+Updates the budgeted amount for a category in the current month.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `category_id` (string, required): The ID of the category
+- `budgeted` (number, required): The budgeted amount in milliunits
+- `dry_run` (boolean, optional): Validate and return simulated result; no API call
+
+**Example Request:**
+```json
+{
+  "name": "update_category",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "category_id": "category-id",
+    "budgeted": 50000
+  }
+}
+```
+
+## Payee Management Tools
+
+### list_payees
+
+Lists all payees for a specific budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+
+**Example Request:**
+```json
+{
+  "name": "list_payees",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012"
+  }
+}
+```
+
+### get_payee
+
+Gets detailed information for a specific payee.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `payee_id` (string, required): The ID of the payee
+
+## Monthly Data Tools
+
+### get_month
+
+Gets budget data for a specific month.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+- `month` (string, required): The month in ISO format (YYYY-MM-DD, typically first day of month)
+
+**Example Request:**
+```json
+{
+  "name": "get_month",
+  "arguments": {
+    "budget_id": "12345678-1234-1234-1234-123456789012",
+    "month": "2024-01-01"
+  }
+}
+```
+
+### list_months
+
+Lists all months summary data for a budget.
+
+**Parameters:**
+- `budget_id` (string, required): The ID of the budget
+
+## Utility Tools
+
+### get_user
+
+Gets information about the authenticated user.
+
+**Parameters:** None
+
+**Example Request:**
+```json
+{
+  "name": "get_user",
+  "arguments": {}
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"user\": {\n    \"id\": \"user-id\",\n    \"email\": \"user@example.com\",\n    \"trial_expires_on\": null,\n    \"subscription\": {\n      \"trial_expires_on\": null,\n      \"cancelled_at\": null,\n      \"date_first_current\": \"2020-01-01T00:00:00.000Z\",\n      \"frequency\": \"annually\"\n    }\n  }\n}"
+    }
+  ]
+}
+```
+
+### convert_amount
+
+Converts between dollars and milliunits with integer arithmetic for precision.
+
+**Parameters:**
+- `amount` (number, required): The amount to convert
+- `to_milliunits` (boolean, required): If true, convert from dollars to milliunits. If false, convert from milliunits to dollars
+
+**Example Request (dollars to milliunits):**
+```json
+{
+  "name": "convert_amount",
+  "arguments": {
+    "amount": 50.25,
+    "to_milliunits": true
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"original_amount\": 50.25,\n  \"converted_amount\": 50250,\n  \"conversion_type\": \"dollars_to_milliunits\"\n}"
+    }
+  ]
+}
+```
+
+**Example Request (milliunits to dollars):**
+```json
+{
+  "name": "convert_amount",
+  "arguments": {
+    "amount": 50250,
+    "to_milliunits": false
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"original_amount\": 50250,\n  \"converted_amount\": 50.25,\n  \"conversion_type\": \"milliunits_to_dollars\"\n}"
+    }
+  ]
+}
+```
+
+## Diagnostic Tools
+
+These tools help inspect the server, environment, and performance. They do not modify YNAB data.
+
+### diagnostic_info
+
+Returns comprehensive diagnostic information about the MCP server with flexible parameter control.
+
+**Parameters:**
+- `include_memory` (boolean, optional): Include memory usage statistics (default: true)
+- `include_environment` (boolean, optional): Include environment and token status (default: true)
+- `include_server` (boolean, optional): Include server version and runtime info (default: true)
+- `include_security` (boolean, optional): Include security and rate limiting stats (default: true)
+- `include_cache` (boolean, optional): Include cache statistics (default: true)
+
+**Example Request (all sections):**
+```json
+{
+  "name": "diagnostic_info",
+  "arguments": {}
+}
+```
+
+**Example Request (selective sections):**
+```json
+{
+  "name": "diagnostic_info",
+  "arguments": {
+    "include_memory": true,
+    "include_server": true,
+    "include_security": false,
+    "include_cache": false,
+    "include_environment": false
+  }
+}
+```
+
+**Example Response:**
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"timestamp\": \"2024-01-15T10:30:00.000Z\",\n  \"server\": {\n    \"name\": \"ynab-mcp-server\",\n    \"version\": \"0.6.0\",\n    \"node_version\": \"v20.10.0\",\n    \"platform\": \"win32\",\n    \"arch\": \"x64\",\n    \"pid\": 12345,\n    \"uptime_ms\": 3600000,\n    \"uptime_readable\": \"1h 0m 0s\",\n    \"env\": {\n      \"node_env\": \"development\",\n      \"minify_output\": \"true\"\n    }\n  },\n  \"memory\": {\n    \"rss_mb\": 45.2,\n    \"heap_used_mb\": 32.1,\n    \"heap_total_mb\": 40.5,\n    \"external_mb\": 2.1,\n    \"array_buffers_mb\": 0.5,\n    \"description\": {\n      \"rss\": \"Resident Set Size - total memory allocated for the process\",\n      \"heap_used\": \"Used heap memory (objects, closures, etc.)\",\n      \"heap_total\": \"Total heap memory allocated\",\n      \"external\": \"Memory used by C++ objects bound to JavaScript objects\",\n      \"array_buffers\": \"Memory allocated for ArrayBuffer and SharedArrayBuffer\"\n    }\n  },\n  \"environment\": {\n    \"token_present\": true,\n    \"token_length\": 64,\n    \"token_preview\": \"abcd...xyz\",\n    \"ynab_env_keys_present\": [\"YNAB_ACCESS_TOKEN\"],\n    \"working_directory\": \"/path/to/project\"\n  },\n  \"security\": {\n    \"requests_processed\": 1250,\n    \"rate_limit_hits\": 0,\n    \"errors_logged\": 2\n  },\n  \"cache\": {\n    \"entries\": 15,\n    \"estimated_size_kb\": 128,\n    \"keys\": [\"budget_123\", \"account_456\"]\n  }\n}"
+    }
+  ]
+}
+```
+
+### clear_cache
+
+Clears the in-memory cache. Safe; does not modify YNAB data.
+
+**Parameters:** None
+
+Example Request:
+```json
+{ "name": "clear_cache", "arguments": {} }
+```
+
+### set_output_format
+
+Configures default JSON formatting for responses.
+
+Parameters:
+- `default_minify` (boolean, optional): Minify JSON outputs by default (default: true)
+- `pretty_spaces` (number, optional): Spaces to use when pretty-printing (0-10)
+
+Example Request:
+```json
+{ "name": "set_output_format", "arguments": { "default_minify": false, "pretty_spaces": 2 } }
+```
+
+## Error Handling
+
+All tools implement comprehensive error handling with consistent error response formats.
+
+### Error Response Format
+
+```json
+{
+  "content": [
+    {
+      "type": "text",
+      "text": "{\n  \"error\": {\n    \"code\": \"ERROR_CODE\",\n    \"message\": \"Human-readable error message\",\n    \"tool\": \"tool_name\",\n    \"operation\": \"operation_description\"\n  }\n}"
+    }
+  ]
+}
+```
+
+### Common Error Types
+
+#### Authentication Errors (401)
+
+**Cause**: Invalid or expired YNAB access token
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "AUTHENTICATION_ERROR",
+    "message": "Invalid or expired YNAB access token. Please check your YNAB_ACCESS_TOKEN environment variable.",
+    "tool": "list_budgets",
+    "operation": "listing budgets"
+  }
+}
+```
+
+**Solutions:**
+- Verify the `YNAB_ACCESS_TOKEN` environment variable is set correctly
+- Check if the token has expired in YNAB Developer Settings
+- Generate a new token if necessary
+
+#### Authorization Errors (403)
+
+**Cause**: Insufficient permissions for the requested operation
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "AUTHORIZATION_ERROR",
+    "message": "Insufficient permissions to access this resource.",
+    "tool": "get_budget",
+    "operation": "retrieving budget details"
+  }
+}
+```
+
+#### Resource Not Found (404)
+
+**Cause**: Invalid budget_id, account_id, transaction_id, etc.
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "RESOURCE_NOT_FOUND",
+    "message": "The requested resource was not found. Please verify the ID is correct.",
+    "tool": "get_account",
+    "operation": "retrieving account details"
+  }
+}
+```
+
+**Solutions:**
+- Verify the ID is correct and exists
+- Use list operations to find valid IDs
+- Check if the resource has been deleted
+
+#### Rate Limiting (429)
+
+**Cause**: Too many requests to YNAB API
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "RATE_LIMIT_EXCEEDED",
+    "message": "Rate limit exceeded. Please wait before making more requests.",
+    "tool": "list_transactions",
+    "operation": "listing transactions"
+  }
+}
+```
+
+**Solutions:**
+- Wait before making additional requests
+- Implement exponential backoff in your client
+- Reduce the frequency of API calls
+
+#### Validation Errors
+
+**Cause**: Invalid parameters provided to tools
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Invalid parameters: date must be in ISO format (YYYY-MM-DD)",
+    "tool": "create_transaction",
+    "operation": "creating transaction"
+  }
+}
+```
+
+**Solutions:**
+- Check parameter formats and types
+- Refer to the tool documentation for valid values
+- Ensure required parameters are provided
+
+#### Server Errors (500)
+
+**Cause**: YNAB service issues or internal server errors
+
+**Example Response:**
+```json
+{
+  "error": {
+    "code": "SERVER_ERROR",
+    "message": "An internal server error occurred. Please try again later.",
+    "tool": "get_budget",
+    "operation": "retrieving budget details"
+  }
+}
+```
+
+**Solutions:**
+- Retry the request after a short delay
+- Check YNAB service status
+- Contact support if the issue persists
+
+## Best Practices
+
+### 1. Error Handling
+
+Always handle errors gracefully in your client applications:
+
+```javascript
+try {
+  const result = await mcpClient.callTool('list_budgets', {});
+  // Process successful result
+} catch (error) {
+  // Handle error based on error code
+  if (error.code === 'AUTHENTICATION_ERROR') {
+    // Prompt user to update token
+  } else if (error.code === 'RATE_LIMIT_EXCEEDED') {
+    // Implement retry with backoff
+  }
+}
+```
+
+### 2. Parameter Validation
+
+Validate parameters before making tool calls:
+
+```javascript
+// Validate date format
+const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+if (!dateRegex.test(date)) {
+  throw new Error('Date must be in YYYY-MM-DD format');
+}
+
+// Validate amount is in milliunits
+if (!Number.isInteger(amount)) {
+  throw new Error('Amount must be an integer in milliunits');
+}
+```
+
+### 3. Efficient Data Retrieval
+
+Use filtering parameters to reduce data transfer:
+
+```javascript
+// Instead of getting all transactions and filtering client-side
+const allTransactions = await mcpClient.callTool('list_transactions', {
+  budget_id: budgetId
+});
+
+// Use server-side filtering
+const recentTransactions = await mcpClient.callTool('list_transactions', {
+  budget_id: budgetId,
+  since_date: '2024-01-01',
+  account_id: specificAccountId
+});
+```
+
+### 4. Amount Conversions
+
+Use the conversion utility for user-friendly displays:
+
+```javascript
+// Convert milliunits to dollars for display
+const dollarsResult = await mcpClient.callTool('convert_amount', {
+  amount: 50250,
+  to_milliunits: false
+});
+console.log(`Amount: $${dollarsResult.converted_amount}`); // Amount: $50.25
+
+// Convert user input to milliunits for API calls
+const milliUnitsResult = await mcpClient.callTool('convert_amount', {
+  amount: 50.25,
+  to_milliunits: true
+});
+// Use milliUnitsResult.converted_amount in transaction creation
+```
+
+### 5. Caching Strategies
+
+Cache relatively static data to improve performance:
+
+```javascript
+// Cache budget and account information
+const budgets = await mcpClient.callTool('list_budgets', {});
+// Cache for 1 hour
+
+const accounts = await mcpClient.callTool('list_accounts', {
+  budget_id: budgetId
+});
+// Cache for 30 minutes
+
+// Don't cache frequently changing data like transactions
+const transactions = await mcpClient.callTool('list_transactions', {
+  budget_id: budgetId,
+  since_date: today
+});
+// Always fetch fresh
+```
+
+This API reference provides comprehensive documentation for all available tools. For additional information, see the [Developer Guide](DEVELOPER.md) for best practices and common usage patterns.