Candor Finance

Returns an explicitly scoped analytical snapshot built from the requested snapshot datasets and filters, in one response. Use when an analysis needs several datasets together, such as a spending review across accounts. Only datasets declared as snapshot datasets in the Candor schema are available. Dataset reads are recorded in private action history; financial records are not changed.

candor_snapshot

Returns one typed Candor object, or the result of one GET operation in the Candor API. Use when one known object or published read operation answers the question, such as goals.get or goals.list, notes.list, rules.get, transactions.get, accounts.list, or recurring.list. Operation-specific arguments follow that operation's published contract (API reference: https://candor.money/developers). The full response returns in this tool result. The read is recorded in private action history; financial records are not changed.

candor_get

Returns computed comparisons for spending, income, recurring payments, account terms, and investment positions, with basis handles and coverage caveats. Use when the user asks how spending, income, recurring payments, account terms, or holdings changed between periods. Spending and income compare recorded posted totals across inclusive since/until and comparison_since/comparison_until ranges; without ranges, the last complete UTC calendar month is compared with the month before, and the response states both ranges. limit trims the items returned without changing the comparison. When source history is incomplete or evidence is capped, spending and income comparisons are withheld. The read is recorded with its reason and does not change the opening checkpoint, seen activity, attention items, or due notes.

candor_changes

Returns Candor API contracts, not financial records. Use when a dataset's filters or an operation's arguments are not already known. With no selector it returns the workspace schema index; dataset returns one dataset's fields, filters, and coverage contract; operation returns one operation's accepted arguments, input schema, and call shape; query searches the operation catalog, with limit up to 10 (default 10). dataset, operation, and query are mutually exclusive. Workspace and dataset schema reads are recorded in private action history; catalog searches and operation descriptions are local lookups. API reference: https://candor.money/developers

candor_schema

Opens the user's Candor workspace and returns what changed since the last processed opening, the current financial position, saved budgets and goals, saved agent context, this week's review (areas to look into and gaps to fill), what the agent's watches came to, notes come due, and current attention such as budget or goal drift, upcoming payments, and coverage gaps. Call it first in every conversation that touches the user's money, goals, or plans, including a quick check-in, a how-is-it-going question, a life decision that costs or earns money even when money is not named, or a return to something set up before: it says what changed since the last opening, including how each measured goal's figure moved, so answers never rest on figures remembered from an earlier conversation. A first opening also carries a first pass: monthly income, spending, debt payments, and net, each account with its balance and debt terms, and the recurring series. mode=pulse returns a compact inspection signal without a checkpoint. The default opening returns a checkpoint candidate; when it shows new activity, an open.acknowledge action in next_actions marks the opening as processed, and an opening with nothing new records its checkpoint itself. The read is recorded in the workspace's private action history; financial records are not changed. Return workspace context, financial position, saved state, new activity, this week's review, watches, due notes, factual attention, and executable next actions. data.agent_brief comes first and is always present, empty when nothing applies; each entry is a standing instruction about the agent's own upkeep, such as filling an open household fact from the records, with a stable code, the instruction, what it is about, and the next_actions command that carries it out. On the first opening, an opening with no checkpoint, one whose checkpoint is 30 days old, or one with more changes than the bounded count, data.first_pass carries the first pass computed in Candor, each block as columns and rows. months has income, spending, debt payments, and net for up to 24 months with a monthly average over full months and the top spending categories; accounts has each account's name, institution, role, balance, and for cards and loans the rate, required payment, due date, and interest charged over the last 12 months; recurring has active, lapsed, and candidate series. Other openings carry first_pass null. The opening keeps four lists apart, each listing everything it read, and each section that lists something carries about, one sentence on what it holds and what to do with it. review is the latest weekly review, null before the first, with reviewed_on, stale (true once the review is more than eight days old, so it is no longer this week's), quiet_reason (why a review that raised no areas was quiet, otherwise null), and its review.area items (what Candor noticed, why it matters, what is not known, the records behind it as basis, and a reviews.update action that names the area) and review.gap items (the facts worth settling and how to record each). watches are what the agent's own watches came to. due_notes are the agent's notes whose revisit date has come. attention is the factual signals Candor computes, such as a payment due soon, a budget line over, or a stale connection. reviews.list reads earlier reviews, and reviews.update records what came of an area. attention.evidence_guide and attention.fact_questions are empty and attention.states is null; they stay only for older clients. context_needed lists the uncovered standard topics. data.help_depth is how much help the user wants, in_depth by default or essentials when the user asked not to be asked about goals or their household; with essentials, context_needed is empty, the brief keeps to what needs action, and review gaps still list, to settle from the records rather than ask. preferences.update changes it on the user's word. The checkpoint for this opening is data.new_since_checkpoint.checkpoint_candidate. When nothing is new since the last checkpoint, the opening records it itself and new_since_checkpoint.checkpoint_recorded is true. Otherwise the same value is carried as args.checkpoint on the open.acknowledge entry in next_actions, so find that entry by command rather than by position, and acknowledge that exact checkpoint after processing the opening; acknowledgement does not resolve attention or due notes.

candor_open

Previews one POST operation in the Candor API and returns the proposed result without applying it. Use when the user wants to see what a change would do before it is saved. Arguments follow the operation's published contract (API reference: https://candor.money/developers). Previews are recorded in private action history; the proposed changes are not applied and financial records are not changed.

candor_preview

Returns one page of rows from a declared Candor financial dataset, such as transactions or accounts, filtered by the supplied arguments. Use when an answer needs individual records, such as specific transactions, balances, or holdings. Results use limit and cursor pagination; each cursor is bound to the filters of the page that issued it, and the call for the next page is listed in next_actions. The full page returns in this tool result. The read is recorded in private action history; financial records are not changed. Run one bounded query against a declared financial dataset. Inspect the selected dataset schema for accepted filters and defaults; omitting filters uses those defaults. Cursor-paginated results keep records, calculations, and pagination under data.page. Calculations cover exactly the returned records, not later pages or the full workspace. Follow next_actions for the exact continuation, preserving the query filters.

candor_query

Refreshes data from financial accounts the user has already connected to Candor. Use when balances or transactions are older than the question needs. Connecting, reconnecting, or disconnecting an institution happens only in the Candor web app. Connected account details are in the accounts dataset.

candor_connections

Returns one Candor dashboard panel or the standard Overview as text context, structured panel data, and a View in Candor link. Use when the user wants to see a Candor chart or dashboard panel. Hosts that support MCP Apps also render the panel with Candor's dashboard renderer. Panel reads are recorded in private action history; financial records are not changed.

candor_visualize

Creates, updates, or removes typed state in the user's private Candor workspace, such as budgets, goals, categorization rules, notes, and confirmed recurring payments, through validated Candor API operations (API reference: https://candor.money/developers). Use to keep what the conversation settles as it settles, without waiting to be asked: a goal the person describes with the measure that tracks it, a budget, a note of what they said, a rule for what transactions mean; and to send product feedback, which the feedback.submit operation delivers to the Candor team. Declared arguments go in args and the request body goes in input. Saving what you work out with the person (budgets, goals, rules, corrections, notes) needs no separate confirmation from them. An operation that does need one states it in its contract; a recorded reason or a preview is not a confirmation. Some operations have other prerequisites stated in their contract. The open.acknowledge operation marks a processed opening as seen. Returns the changed object or a receipt with status, errors, and next_actions; an invalid operation or argument returns a schema error without writing. Every write is recorded with its reason in the workspace's action history. It cannot move money or change anything at a financial institution.

candor_write