Return read-only finance status: balances, source freshness, trace ids, and stable V1 slots.

List configured income sources, schedule versions, review dates, and generated horizons.

Create or update an income source and schedule version after user confirmation.

Import normalized calendar facts into local storage.

This tool expects source-specific calendar import to happen before the call. Facts should include fact_type, date, source, and optional external_id, calendar_id, related entity, title, confidence, notes, and payload.

List local normalized calendar facts with optional filters.

Create or update an obligation and exact dated instances.

List local canonical obligations and optionally their dated instances.

List obligation instances that need review, such as estimated amounts due for refresh.

List card-spend inputs that feed future statement estimates without directly reducing checking.

Generate dated income obligation instances from configured income schedules.

extra_closure_dates accepts YYYY-MM-DD dates imported from a payroll or calendar source for one-off local closures.

Scan transaction history and discover reviewable charge-pattern candidates.

This is the background-discovery entry point: it groups related transactions by merchant and account, proposes schedule/amount/cash-impact/review policies, and stores durable candidates in a review queue. It is idempotent and never writes canonical obligations or moves cash flow. Options support min_evidence, include_inflows, and link_existing_obligations.

List charge-onboarding candidates ordered by estimated monthly cash impact.

By default returns only the active queue (candidates still awaiting a decision). Pass status to filter exactly, or include_resolved=True to see decided/paused candidates such as deferred or rejected ones.

Return the single highest-priority unresolved charge-onboarding candidate.

Record a review decision against a charge-onboarding candidate.

Supported actions in this slice: defer, reject, needs_more_evidence, in_review, reset. Applying a candidate into a canonical obligation (accept/apply) or restructuring (merge/split) is a separate guarded slice and is rejected here.

Preview the canonical obligation and dated instances that applying would create.

Read-only and writes nothing. Use this to show a reviewer exactly what would land in the cash-flow model (obligation, instances, schedule summary, and warnings) before committing to apply.

Promote an accepted candidate into a canonical obligation plus dated instances.

This is the guarded write that turns a reviewed candidate into cash-flow truth. By default the candidate must already be accepted (record an accept decision first). Writing is idempotent: re-applying the same window updates instances in place instead of duplicating them.

Group card-statement-input charges into the statement cycle that pays them.

Deterministic and idempotent. Builds statement cycles from the target obligation's statement instances (those with a statement close date) and assigns each card input to its cycle, reporting any inputs that fall past the last known statement close as unrolled.

List statement cycles for a card obligation with their aggregated card-input evidence.

Fill unconfirmed statement estimates from the card-input rollup, guarded.

Only statement instances whose amount is an unconfirmed projection are recomputed, as baseline (expected non-modeled card spend) plus the rolled-up modeled card inputs for that cycle. Portal/observed amounts are never overwritten. Idempotent.

Match expected obligation instances against observed transactions.

Deterministic and idempotent. Records the best transaction match per instance as review evidence (amount + date + merchant scoring). Conservative by default: matches are not silently marked paid (set options.auto_mark_paid to opt in), unmatched past-grace instances become needs_review not overdue (set options.flag_unmatched_needs_review to opt in), and card-statement-input instances are skipped (they settle via the statement, not a checking match).

List obligation instances matched to a transaction, with score and evidence.

List expected obligation instances with no matching transaction (drift inputs).

Detect evidence-backed drift findings, ordered by severity.

Finds missing expected obligations (past due, no matching transaction), stale estimates (review date passed), amount changes (charge happened but differs materially), and unexpected recurring charges (discovered by onboarding but not yet modeled). Deterministic and idempotent. When persist is true, findings are upserted and disappeared ones marked resolved.

List stored drift findings, filtered by status (default active) and type.

Render the day's review items (drift findings) as a Todoist task + subtasks.

Read-only and sends nothing. Returns the parent task and per-item subtasks with specific guidance, so the user can see the review batch before any write.

Record the day's review batch in the durable action outbox. No live write.

Idempotent (one batch per day). dry_run (default true) records the payload without intending to send; dry_run=false marks it pending for a sender that is intentionally not configured. Nothing is ever sent to Todoist here.

Process outbox items. Live Todoist sending is gated OFF by default.

Dry-run items are always simulated. Pending items send to Todoist ONLY when TODOIST_WRITE_ENABLED is set in the finances .env AND a token + project id are configured; otherwise they are marked awaiting-integration (no external call). When enabled, sending is idempotent - one task per outbox key, updated in place on rerun rather than duplicated.

List durable action-outbox items (intended external writes) and their status.

Run the finance pipeline as one auditable background run.

Orchestrates: scan charge candidates, reconcile transactions, detect drift, and preview the Todoist review batch (dry run). Records a run record plus an ordered operation-event log. A failing step is logged and the run continues (partial_success). Returns the run id, trace id, status, and step summaries.

Return a background run record plus its ordered operation-event log.

List recent background runs with their status and timing.

Store a finance memory (a correction, decision, or fact to recall later).

Idempotent by (kind, source, text). Use kind to scope memories, e.g. 'decision', 'correction', 'fact'.

Retrieve the most relevant finance memories for a query, under a context policy.

Records are scored by similarity, then filtered by min_score, capped at k, and bounded by a max_tokens budget. The result reports how many records each limit dropped so the amount of memory entering context is explicit.

List stored finance memories, optionally filtered by kind.

Delete a finance memory by id (e.g. when a correction is no longer true).

Import cashflow-candidate Todoist tasks as canonical one-off obligations.

The local DB stays the source of truth; Todoist is the origin for one-off obligations only. Idempotent by task id. A checked/completed task sets a review date but is never auto-marked paid; a deleted task cancels its instance; a task resembling a recurring obligation is flagged needs_review_dedup_conflict instead of imported. If tasks is omitted, reads cashflow_candidate tasks from the local todoist_tasks snapshot.

List Todoist-to-obligation sync records, optionally filtered by status or task id.

Resolve a flagged Todoist dedup conflict: import_anyway, skip, or merge.

Migrate the complete obligation set from a legacy source into canonical rows.

source is 'obligations_yaml' (trusted, machine-readable) or 'cashflow_md' (stale narrative, imported as needs_review). Instance-level dedup skips anything already modeled; ambiguous rows become needs_review. dry_run (the default) computes the full plan and writes nothing. Reads the legacy file read-only.

Evaluate operating guardrails (cash floor, drift threshold, window age, debt avalanche).

Returns findings ordered by severity. Reads balances and drift from the DB. When persist is true, records the evaluation (pass/fail per rule).

List recorded guardrail evaluations, optionally filtered by date or rule.

Idempotently seed the default guardrail rules into the database.

Pull live accounts, balances, and transactions from SimpleFIN into the DB.

Reads SIMPLEFIN_ACCESS_URL from the finances .env at runtime (never returned). Read-only against SimpleFIN; idempotent upsert by transaction id. When start_date is omitted, incremental=true resumes from the last synced transactions (cheap for a daily run); otherwise it pulls lookback_days (SimpleFIN caps the window at 90 days). Returns counts and any warnings.

Pull the live Todoist board (tasks + sections) into the local DB, read-only.

Reads TODOIST_API_TOKEN and the project id from the finances .env / obligations.yaml at runtime (never returned). Normalizes each task into the cashflow fields the onboarding importer uses, upserts by id, and marks tasks no longer seen as deleted. Does NOT write to Todoist.

Validate the pipeline on live data without touching the committed snapshot.

Copies the database to a throwaway working DB, optionally pulls live SimpleFIN

• Todoist into the copy, then runs the read pipeline (onboarding scan, reconciliation, drift, guardrails) and returns a report with integrity checks (e.g. no orphaned statement targets after a card rename). The source database is never mutated.

The daily finance summary (replaces just daily): balances, cash-flow projection, upcoming obligations, drift/review items, recurring candidates, and guardrail status, each with provenance. Set render_markdown for a cash-flow.md-style narrative under the 'markdown' key. Read-only.

List recorded transaction matches whose obligation instance still awaits confirmation (the day's close-out queue). Read-only.

Mark a reviewed obligation instance paid using its recorded transaction match. Guarded: requires a recorded match (run reconcile first); never auto-pays. Reversible with unconfirm_reconciliation_match.

Reverse a confirmation: return the obligation instance to 'expected' and clear the matched-transaction evidence.

Parallel-run parity: diff a legacy cash-flow.md against the new daily digest.

Reads the legacy markdown the caller points at (supply a fresh one from your own daily ritual); never runs the legacy ritual or writes any legacy file. Reports matched / missing-in-new / extra-in-new / amount-or-date-changed obligations with a severity each, plus the working-cash delta. Set render_markdown for a short parity summary under the 'markdown' key.

Summarize outflow spending over a date range, grouped by category, merchant, or month: totals, counts, top buckets, a month-over-month trend, and the transaction ids behind each bucket. Transfers and income are excluded by default. Read-only. Set render_markdown for a summary under 'markdown'.

Check that every headline dollar figure in a finance payload (a get_finance_status or get_daily_digest result) traces to a source: working cash to the latest operating-account balance snapshot, each upcoming obligation to its instance row, each projection endpoint recomputable from those. Returns a grounding report flagging any number it could not trace. Read-only - use it to verify a finance answer before relying on it.

Materialize past-due instances for active recurring obligations over a trailing window and reconcile them against posted transactions, so the digest can answer "did rent / Amex / Apple clear this cycle?". Past instances do not enter the cash-flow projection (forward-only); no payment is fabricated - matches come from the normal reconciliation matcher.

Apply HIGH-confidence, well-evidenced direct-checking recurring candidates (e.g. a car payment) as proper obligations so they enter the cash-flow projection and the runway becomes accurate. Conservative: only confidence=high direct-checking with >=3 occurrences; everything else stays in the review queue.

Cancel future instances of a Todoist-imported obligation that duplicates a proper recurring obligation (e.g. a stale one-off "New York Times" $28.62 vs the recurring "New York Times subscription" $30.30). Conservative subset match; reversible (status -> canceled).