ExpenseBot

Correct category, business purpose or user-supplied attendees on exact recorded expenses. First search_expenses for full expenseId values. A grounded preview is automatic with confirm omitted/false; show exact count and before/after changes, ask approval once, then repeat identical operationId, selection and change with confirm:true. Premature confirmation returns preview. Never infer attendee names/business context. attendeeMode add preserves existing attendees; replace changes only that Notes segment. Preserve card, description, inbox and other structured Notes segments. Formula Notes/Notes overflow are safely skipped. Terminal result gives applied/conflicted/failed counts and supports Undo. This tool does not omit duplicates or change amounts/dates or broad Calendar matching. Unsupported or over-100-row cleanup: https://www.expensebot.ai/review-expenses?source=mcp.

correct_expenses

Create a standalone group/tag without selecting or changing any expenses. The first call prepares a preview; after the user explicitly chooses to create it, send confirm:true with the returned operationId (fresh duplicate checks run). A first call with confirm:true still returns a preview. An exact canonical duplicate is a no-op; archived tags are not reactivated. Similar names are returned as choices; set allowSimilar:true only when the user explicitly chooses a distinct new group despite them. Use list_tags to inspect all groups.

create_tag

Create the exact invoice previously returned by prepare_client_invoice. This is a confirmed write: it revalidates the report snapshot and client identity, creates a private editable Google Doc plus private PDF and DOCX copies, records the issued invoice, and supersedes an older active invoice for the same report. It does not send email or create an Income row. If tax is positive, confirmTax must be true.

create_client_invoice

Create a report for clear date/client/project/trip/category/merchant criteria. Tags group clients/projects/project codes/trips; list_tags if unclear. excludePersonal=true excludes both Personal tag and Personal expense category, matching Report Wizard. Returns summary, exact report/Bill Client links, applied filters and prefilled Report Wizard fallback for visual criteria. Group-scoped reports include matching rows not on another ordinary report. Optional recipient sharing. No unreported matches: no duplicate; explain existing Reports. Terminal accountingHandoffUrls are role-aware: use only the requested destination; opening a reviewed flow is not export proof. Complete directly; no check_compliance/get_report_details/tax/deductibility analysis before/after unless explicitly requested.

create_report

Update a single existing expense row's category, tag, merchant or business purpose (e.g. 'recategorize expense X to Meals', 'tag it Client – Acme'). Identify it only by the exact expenseId from search_expenses (the full Receipt ID from Column Q); never a date, displayed number or sheet row number. Two-phase: calls with confirm omitted/false return a current→proposed preview and change nothing; after user confirmation, confirm:true applies it. If the expense is not found, search once for a current exact expenseId; never retry the same stale ID. If a business-purpose update exceeds the Notes capacity, stop and send the user to https://www.expensebot.ai/review-expenses?source=mcp. Paid with is also editable as fields.paidWith, separately from other fields: optional bookkeeping label only, no status/settlement changes. Blank clears the override and reveals source/default. Reuse expectedPaidWith from preview on confirm. Amounts, dates and raw notes require Review Expenses. Does not create or delete rows.

update_expense

Fetch full details for a specific item returned by `search`. The id encodes the item type: • 'expense:<expenseId>' — the durable Column-Q Receipt ID returned by `search`, URL-encoded, e.g. 'expense:RR-123%3A%3Adrive%2Ffile%209'. Never a sheet row number: rows move when the sheet is prepended. • 'report:<reportId>' — the alphanumeric Firestore document id from `search` or `list_reports`, e.g., 'report:FQqDglExofsyyQv7aYy4' • 'kb:<entryId>' — the knowledge-base entry id from `search` Always use the id exactly as returned by `search` or `list_reports` — do not invent or modify the trailing portion. Returns the full text content + metadata for the AI to cite.

fetch

Fix exact recorded expenses only after an explicit request about check_compliance findings. Get full expenseId values from search_expenses; never select all report rows or infer purpose/category/attendees. Like correct_expenses: first call always returns a grounded preview without changes, even with early confirm:true. Show exact changes, ask once, then repeat identical operationId/selection/change with confirm:true after explicit approval. Terminal result gives applied/conflicted/failed counts, status and Undo. Grouping: group_expenses. Unsupported/over-100-row cleanup: https://www.expensebot.ai/review-expenses?source=mcp.

fix_compliance

Get the full financial and delivery summary for one issued client invoice, including subtotal, markup, tax, advance applied, balance due, dates, status, source report, and private Google Doc/PDF/DOCX links when available. Provide invoiceId or invoiceNumber — one is required; invoiceNumber is accepted only when it is unique. Read-only.

get_client_invoice

Read one existing expense from the authenticated user's ExpenseBot spreadsheet. Supply the exact expenseId returned by search_expenses (Receipt ID in Column Q), or the user's specified rowNumber. Never invent an identifier. Returns sheetName, rowNumber, headers, values, labeled fields and, when available, reviewExpenseUrl. This tool does not edit, submit, delete, share, or scan anything. Also returns Paid with context (unavailable differs from blank) and typed bookkeeping paymentStatus, never bank settlement proof.

get_expense_by_id

Use this when the user asks about income already recorded in their ExpenseBot Income tab. Read totals; group by source, category, month, payment method or tag; filter by dateRange/incomeTagPrefix. Query supports period comparisons (e.g. 'income YTD by source', 'income this year vs last'). Returns message and data with total and optional breakdown, comparison, sampleMeta. No scanning, imports, mutations, tax returns or liability determination.

get_income_summary

Mileage totals and month/client/purpose/category breakdowns; country-aware IRS/CRA cents-per-mile/km deduction estimates. Use for mileage this year/by month/for Acme, business miles last quarter or deduction estimate. Supports YoY/MoM/QoQ comparisons. Returns message/data with totalDistance, optional deductionEstimate/breakdown/comparison/sampleMeta.

get_mileage_summary

Per-tag P&L — revenue, cost, profit, and margin grouped by tag (per-client, per-property, per-event, per-realtor-deal). Requires both income AND expense rows to be tagged with matching labels. Common tag-prefix shortcuts: 'Prop –' (rentals), 'Client –' (client billings), 'Wedding –' (events), 'Realtor –' (real estate deals). Examples: 'per-tag P&L this year', 'profit by client', 'profit by property', 'profit on the Smith wedding', 'per-client P&L this year vs last' (YoY). Supports YoY / MoM / QoQ comparison phrasing. Margin renders as multiplier in loss territory. Defaults to year-to-date if no date range given.

get_per_tag_pnl

Compute Profit & Loss (P&L / net income / margin) by combining the Income tab with expense tabs. Examples: 'am I profitable this year', 'P&L for Q1', 'net income last quarter', 'what's my margin', 'P&L this year vs last' (YoY). Supports period comparison — YoY, MoM, QoQ, same-month-prev-year. Margin renders as multiplier in loss territory ('expenses 5.4× revenue') so the user gets a readable signal instead of '-436.9% margin'. Returns: { message, data: { revenue, expenses, netIncome, margin, comparison?, sampleMeta? } }.

get_pnl

Get full details of a specific expense report including all expenses, totals, and compliance status. Use only when the user explicitly asks to inspect an existing report's details. Without checkFreshness:true, returns the stored report only. When explicitly requested together with analysisRequested:true, freshness reads canonical Google Sheets sources with a 5-second bound; if full tax-year replay is unavailable, status is unknown, not current. Never call this as a preflight or follow-up to creating, sharing, or billing from a report; those tools already return the requested result and links.

get_report_details

Get a short-lived direct PDF download for one exact authorized expense report, plus the exact highlighted in-app report link. Use the in-app report for CSV, XLSX, receipt ZIP (when available), comments, invoicing, and other visually reviewed actions. Use list_reports first to find the reportId.

export_report

Summarize the user's recorded expenses with totals and breakdowns by category, merchant, month, tag, source, or payment method. Supports date ranges, period comparisons, and total, count, or average metrics. Read-only. Returns: { message, data: { total, breakdown?, comparison?, sampleMeta? } }.

get_spending_summary

Group exact recorded expenses for a user-named client/project/trip/job, optionally creating a report. ExpenseBot resolves existing group names and proposes creation only when needed. Use exact expenseId values from search_expenses. Preserve assignments unless explicitly asked to replace (replaceExistingTags:true). A grounded preview is automatic. First call with confirm omitted/false; show exact rows, count, totals, group, exclusions and conflicts, then ask approval. After explicit approval repeat the same operationId and selection with confirm:true; a premature confirm:true is converted to preview. For group-and-report set createReport:true on that confirmation and use its result, never a separate broader create_report query. excludePersonal:true removes both Personal-tagged and Personal-category rows before preview, preserving their marker. Rows on other ordinary reports are excluded; no matches creates no duplicate and links to Reports. Returns exact report/Bill Client links. Call the destination a group, not a tag. Treat preview totals as provisional; use only terminal count/total/currency without reconciling earlier totals. Bill Client opens a reviewed handoff; it does not mean an invoice was created, sent, or confirmed. Sharing separately requires share_report recipient confirmation. Be concise; no unsolicited tax/substantiation advice or check_compliance/get_report_details/tax tools unless explicitly requested.

group_expenses

Use this to import the user's CSV/TSV/text income export (max 500 KB). Step 1 stages a duplicate-checked previewId without writing Income rows. Show it and obtain approval. Step 2 uses confirm:true and that previewId to write the approved rows/edits; duplicates require explicit keep approval. Unknown or expired previews never write (15-minute expiry). Return spreadsheetUrl and reviewIncomeUrl after success. Accepts user-provided attachments or inline text, not arbitrary web URLs.

add_income_from_csv

Import income from attached JPEG/PNG/WebP/HEIC/HEIF screenshots/images or PDF (payment/wallet/payout/bank statement; max 10 MB). Step 1: file WITHOUT confirm uses Add Income's parser and Income-tab duplicate check. Returns previewId, exact count, currency totals, rows, duplicate flags/rejections; parses only, saves nothing. Attachment is not write consent. Show rows/duplicates. Step 2: confirm:true + previewId writes only user-approved selectedIndexes/keepBothIndexes/rowEdits/tag/bulkNote. Skip flagged duplicates unless explicitly approved in keepBothIndexes. Unknown/expired previews (15 minutes) never write. Success: show spreadsheetUrl + reviewIncomeUrl. Mixed income/expense or many edits: Add Income link from get_spreadsheet_url.

add_income_from_file

List the user's issued client invoices (accounts receivable) — who owes them money, how much, and when it is due. Examples: 'which invoices are outstanding', 'what does Acme still owe me', 'any overdue invoices', 'how much am I waiting to get paid'. status accepts 'active' (default), 'open', 'overdue', 'needs_review', 'paid', 'void', 'superseded', or 'all'. Returns invoice numbers, status, totals by currency, delivery state, and private document links. Read-only.

list_client_invoices

List the user's configured expense categories and billing accounts. Use this BEFORE calling tools that need a category (add_cash_expense, add_mileage_entry, create_report) so you pass the user's actual category names, not guesses. Returns the live list from their spreadsheet.

list_categories

List the user's expense reports with pagination. Filter by status (All, Draft, Submitted, Shared). Each exact report includes its app, Bill Client, and accounting handoff URLs. Use the matching accounting URL only when the user explicitly asks to send or export that report; the app keeps organization, mapping, preview, and final confirmation.

list_reports

List ExpenseBot's fixed income tax categories. Unlike Expense Accounts, these are not user-configured. Use this BEFORE calling add_income so you pass an exact canonical category instead of guessing.

list_income_categories

List card refunds, cashback/rewards, and statement credits that ExpenseBot has already recorded — either as negative expenses or matched against the original charge. Examples: 'did my refund come through', 'show my statement credits', 'was that return recorded'. Returns the most recent items (default 25, newest first); narrow with dateRange. Read-only: it never scans cards, changes review decisions, or adds rows.

get_credits_refunds

List the user's configured groups. ExpenseBot stores clients, projects, project codes, properties, and trips as tags (for example 'Client: Acme', 'Vegas Trip', or 'Property: 123 Main'). Use this when the user asks 'what groups/projects/clients do I have?' and before filtering, grouping, or reporting when the intended existing name is unclear.

list_tags

After confirmation, add a receiptless expense or client-provided expense advance to the expense sheet. Ordinary expenses: list_categories first; use a configured Expense Account. Advances: isClientAdvance=true + clientName reuses/creates the canonical client group, applies Cash advance received and writes a negative expense. Only client money provided before spending; never for vendor refunds, reimbursements, earned fees, retainers or generic deposits. Multiple/incomplete entries, refunds, tax/tip/per diem: Manual expense link from get_spreadsheet_url.

add_cash_expense

Log exactly one confirmed income payment (cash/check/Stripe/etc.) to Income, e.g. income absent from Gmail/Plaid. Never loop over statements/exports/tables/lists. Multiple payments: add_income_from_csv for CSV/TSV/text or add_income_from_file for image/PDF; both duplicate-check, preview and require confirmation. Call list_income_categories first; use fixed tax categories. Omitted category defaults to Service income; unknown is rejected.

add_income

Log one business trip as a calculated-value expense row. Requires a configured mileage rate (cents/km or cents/mi) and unit (mi/km). For route calculation, mileage settings, repeated trips, calendar/rideshare imports, per diem or visual review use Mileage and travel from get_spreadsheet_url.

add_mileage_entry

Mark an issued client invoice as paid after explicit confirmation. Requires a strict calendar-valid paidDate in YYYY-MM-DD format. This updates the accounts-receivable invoice record only; it never creates or moves an Income row. Record the actual payment separately or link an existing Income row.

mark_client_invoice_paid

Return the master Google Sheet and authenticated workspace links with labels/usage. Show only 1–2 relevant returned links. Open/view/edit spreadsheet: Sheet. Receipt added: Review expenses + Sheet; income added: Review income + Sheet. Gmail scan/connection: Scan Gmail. Bank/card connection/reconciliation: Reconcile. Configuration: Automation Hub/General Settings. Category/G/L/account codes: Category management. Client/project/trip groups: Group management. Personal classification: Personal rules. Client billing: use returned clientBillingHandoffs for the current step: manageClients (client list), tagReadyExpenses (blank/default-Business rows), createClientReport (report by assigned group). To perform a named client's exact expense grouping, use search_expenses then group_expenses with grounded preview and explicit confirmation. Google Photos: returned authenticated picker with consent. Receipt storage: returned Drive folder only; never invent/request a folder ID. Complete unambiguous cash expense/mileage: direct write tool. Multiple/incomplete expenses, credits/refunds, tax/tip/per diem or visual review: Manual expense. Route calculation, mileage settings/repeated trips/calendar/rideshare/per diem/review: Mileage and travel. Income screenshot/PDF/CSV without chat attachment or complex review: Import income, which previews every row before saving. Team setup: returned role-aware handoff (solo owner: Add teammates; owner/co-admin: Team Management); explain owner-access requirements instead of showing a broken link. Complex reports: Create report. Read-only; no row changes.

get_spreadsheet_url

Parse a natural language expense description into structured fields. Does NOT add the expense — just returns the parsed fields for review. Example: "Lunch at Chipotle $15.50 today" → {merchant: "Chipotle", total: 15.50, ...}

parse_expense

Prepare a client invoice from a saved ExpenseBot report without creating it. Reads canonical report rows, allocates a unique invoice number, verifies the client ledger identity and advance, and returns exact totals plus a short-lived preparationId. Call this first, show the preview to the user, then call create_client_invoice after explicit confirmation. It reserves the invoice number and preview for 30 minutes but creates no invoice, document, Income row, email, or payment.

prepare_client_invoice

Preview explicit setup answers; never infer settings or recipients. Show changes/access/recipients; after explicit approval confirm only proposalId + confirm:true. Owner/revision-bound; rejects changed state. Lost response: proposalId + status:true; never resend blindly. Read get_setup_status after completion. Personal Rules require validation/activation; invitations are not accepted client access. OAuth/bank/required reviews use returned screens. No financial writes or client acting.

complete_setup

Process specific Gmail emails as receipts. Pass Gmail message IDs and they'll be converted to PDF, extracted by AI, and added to the user's expense spreadsheet. Max 25 emails per request. Requires Gmail to be connected in ExpenseBot settings.

process_gmail_receipts

Read authoritative setup, known answers, next question and eligible actions for the current workspace. Ask only missing prerequisites; optional setup must not block a specific expense task. Unknown is not empty/complete. No client acting/writes.

get_setup_status

Request an exact accounting package only after checking reviewed direct/import-file destinations and finding no match. Do not use this for a listed or Beta destination or general compatibility. A confirmation-gated write: after user approval, creates one deduplicated request bound to the authenticated account and emails ExpenseBot's internal team. Does not create an integration or immediate availability. For accepted/already-recorded requests, say ExpenseBot will email an update within one week.

request_accounting_integration

Preview then post an owner's report to accounting. Step 1: provider/reportId, optional mode/mappings, NO confirm. Reads live report/destination, enforces Omit/Personal/split/date/currency rules and Zoho bank-feed checks; returns complete frozen proposal + proposalId, posts nothing. Show complete proposal and ask approval. Step 2: ONLY provider/proposalId/confirm:true, never mappings. Revalidates live state and rejects changed reports/mappings; account-bound proposal only. No client acting. Agent posting: Zoho Books (zoho_books) only. QuickBooks Online/Xero/Wave/FreeAgent cannot yet freeze/revalidate shareReport plans; use their web flows.

send_report_to_accounting

Accountant-only month-end overview of accepted client workspaces. Returns page-level readiness and affected-client category counts with an authenticated Client Reports link. Use for 'how many clients need attention before month end'. No client identities, amounts, or individual items are returned; select a client in ExpenseBot to resolve items. Unavailable sources remain unknown. Each page uses the current roster; do not combine pages into a verified total.

list_client_close_readiness

Review one calendar month's recorded income, spending, net, top categories/merchants and unusual alerts ('monthly review', 'how did last month go', 'what did I make and spend'). Defaults to last completed month. Advisory estimates are not tax advice. closeReadiness gives recorded-book checks/Action Needed links; explain unknown coverage/limits. Never closes books or certifies tax completeness.

get_monthly_books_review

Review trips from the engine behind Review Expenses Find. Default is high-confidence only; for the trip list set includeCandidates:true: real trips first (AI-reviewed order when available), second homes and regular spots grouped; page with offset while remaining > 0. Name a trip with destination (e.g. "Copenhagen"); mode:area with area lists every expense in a country or city. Show dates, recorded locations, count and uncertainty; locations are not travel or client proof. Copy exact selections to group_expenses with a user-chosen trip/client name and confirm:false, then request approval. Possible additions stay out unless the user includes them (includePossibleAdditions:true). Merge/deduplicate selections for one destination; separate destinations need separate confirmations. Preserve existing assignments, Personal and read-only rows. Never infer clients or countries from currency. clientEmail mode is read-only.

get_trip_suggestions