Maru

Create a category. Refuses, as the app does, a name reserved for transfers ("Transferência", "Transfer") and a synonym of a default category (e.g. "Restaurante" for "Alimentação"): the error names the default to use instead. Refuses a name another category already has. Only the tenant owner can create one. Call list_categories first to reuse an existing category instead.

create_category

Create a center. Refuses a name another center already has. Only the tenant owner can create one. Call list_centers first to reuse an existing center instead.

create_center

Create a counterparty. Refuses a name another counterparty already has. Only the tenant owner can create one. Call list_counterparties first to reuse an existing counterparty instead.

create_counterparty

Create a recurring planned transaction (a recurrence template), as the app's form does when a recurrence is chosen: it repeats weekly, biweekly, monthly or yearly from date, until end (or forever). It is always planned; each occurrence shows as projected until it is materialized (materialize_occurrence) or the recurrence is removed (remove_recurrence). list_recurrences shows the projected occurrences.

create_recurring_transaction

Create one manual transaction (planned or realized), as the app's transaction form does. Status defaults as in the app: planned when the date is in the future or the account is not a cash account (bank and card rows normally come from statement imports), realized otherwise. A realized row on a non-cash account breaks Maru's import rule and is refused unless the person agreed (acceptManualRule). For a credit card, effectiveDate is the bill date. For a transfer between accounts use the transfer operations; for a repeating one use create_recurring_transaction. Fails with transaction_limit_reached when the tenant's credits are used up.

create_transaction

Create a new transfer between two of the person's accounts, as the app's transaction form does with type Transfer: two linked transactions, an outgoing one on `from` and an incoming one on `to`, no category. Status defaults to planned, as in the app, because bank and card movements arrive by importing statements; a realized transfer touching a non-cash account breaks that rule, so it is refused unless the person confirmed it and you pass acceptManualRule. Uses two transaction credits. To pair existing transactions use transfers_link instead.

create_transfer

Delete accounts by id (up to 200). An account's own "Initial Balance" opening row is deleted with it, as the account form owns it; any other transaction blocks the delete, so this refuses up front and names those accounts: delete or move their transactions first with the transaction operations. Destructive: the first call returns the plan and changes nothing; call again with the confirm token once the person agrees. Only the tenant owner can delete accounts.

delete_accounts

Delete categories by id (up to 200). Destructive: the first call returns the plan (each category with how many transactions use it, and what happens to them) and changes nothing; call again with the confirm token once the person agrees. Its transactions stay and become uncategorized (the uncategorized filter finds them). Move them to another category first if that matters. Only the tenant owner can delete. Get ids from list_categories.

delete_categories

Delete centers by id (up to 200). Destructive: the first call returns the plan (each center with how many transactions use it, and what happens to them) and changes nothing; call again with the confirm token once the person agrees. Its transactions stay and lose their cost center. Move them to another center first if that matters. Only the tenant owner can delete. Get ids from list_centers.

delete_centers

Delete counterparties by id (up to 200). Destructive: the first call returns the plan (each counterparty with how many transactions use it, and what happens to them) and changes nothing; call again with the confirm token once the person agrees. Its transactions stay and lose their counterparty. Move them to another counterparty first if that matters. Only the tenant owner can delete. Get ids from list_counterparties.

delete_counterparties

Delete explicit manual transactions, as the app's Delete does. Destructive: the first call returns the plan (each row with its date, amount, description and every side effect) and deletes nothing. Deleting one leg of a transfer deletes the other leg too; deleting a recurrence template stops its projections and keeps its materialized occurrences, detached; an account whose opening balance it was loses that link. Imported rows, and transfer legs whose other leg is imported, are refused and listed with the reason (undo an import with the import operations). To only stop a recurrence and keep the row, use remove_recurrence.

delete_transactions

Fuzzy-match free-form text against the user's categories, counterparties, accounts, or centers. Always call this first when the user mentions a name in natural language ("restaurantes", "Nubank", "filial SP"), then pass the matched UUID to other tools as a filter. Returns up to `limit` candidates sorted by score; pick the highest unless the user clearly meant another match.

match_entity_name

Fetch transaction IDs matching a filter. Use this when you need a count or want to follow up with search_descriptions over a specific subset. Capped at `limit`; check `truncated` before drawing conclusions about totals.

list_ids

One transaction in full, decrypted: date, effective date, amount, description, notes, account, category, counterparty, center, status, voided, whether it was imported, its transfer counterpart, its recurrence (template or occurrence) and whether it is an account's opening balance. Use it before changing a transaction, to show the person what is there.

get_transaction

List past statement imports, newest first, as the app's Import History shows them: file name, account, statement period, rows imported, and the rows and sum as they stand now (`edited` when the import's transactions were changed or removed since). Use an id with undo_import, or list its transactions with the transaction tools by importId.

list_imports

Import statements: the same judgment as import_preview, then commit every row that is not open, and post the statement's opening balance as the account's initial balance when the account has none (as the app does). Destructive: the first call returns the preview's judgment (counts per file, balance effect, opening balance, rows left out) as the plan; call again with its confirm token to commit exactly that. Run import_preview first and resolve open rows with decisions. When several files are imported together each is re-judged after the previous one is committed, so a later file can pair with rows the earlier one created. Undo a whole import with undo_import. Rows the web app commits without asking (new rows, certain duplicates skipped, auto-matches, investment yields) are judged the same way. Rows the web would put in front of the person are returned under `open` with their reasons (match, probable_duplicate, unmatched_payment = a card payment with no bill behind it, "Pag. sem fatura"), candidates and allowed actions, and are LEFT OUT of a commit until decisions cover them. Decisions are an object: {"applyOpeningBalance"?: boolean, "files"?: {"<file name>": {"account"?: "<id|name>", "dueDay"?: 1-31}}, "rows"?: {"<rowId>": {"action"?: "accept"|"link"|"transfer"|"skip", "transactionId"?, "account"?, "category"?, "counterparty"?, "center"?}}}. Row ids are stable for the same file and account. Non-open rows are counted per file; pass all, or offset and limit, to list them.

import

The Reports screen: income or expenses of a year (or one month of it) ranked by category, counterparty or cost center, top 50, with each one's share and the rest summed as othersTotal. Transfers, voided rows and card payments without a bill are left out, as in the app. name null is the "uncategorized" or "without center" bucket. Use aggregate instead for any other date range or filter.

breakdown

Make a transaction one leg of a transfer, as the app's "Create Transfer" dialog does. With linkedTransactionId, links two existing transactions on different accounts with opposite amounts (both lose their category and are no longer voided). With account, creates the other leg on that account instead (one transaction credit): for an expense the transaction stays on its account and the new income leg goes to `account`; for an income the transaction moves to `account` as the outgoing leg and a new income leg is created on its original account. Destructive (categories are cleared): the first call returns the plan; call again with its confirm token. Find candidates with transfers_candidates first; undo with transfers_unlink.

transfers_link

List the bank, investment, credit card and cash accounts with everything the accounts screen shows: decrypted name, type, bank (code and name), card brand and due day, opening balance (the "Initial Balance" transaction), the statement balance set for reconciliation, current realized balance, how many transactions each holds, and how far statements have been imported. Use it to find account ids for the other operations.

list_accounts

List every category of the tenant with its decrypted name, color, icon and how many transactions use it (transactionCount, with their income and expense totals over all time). Use it to find ids before create_category, update_category, rename_category or delete_categories.

list_categories

List every center of the tenant with its decrypted name and how many transactions use it (transactionCount, with their income and expense totals over all time). Use it to find ids before create_center, rename_center or delete_centers.

list_centers

List every counterparty of the tenant with its decrypted name, color and how many transactions use it (transactionCount, with their income and expense totals over all time). Use it to find ids before create_counterparty, update_counterparty, rename_counterparty or delete_counterparties.

list_counterparties

Recurring transactions (templates) and their projected occurrences between from and to, as the app's transaction list projects them: occurrences already materialized are not projected again. Use it to find the templateId and date for materialize_occurrence, or a templateId for remove_recurrence.

list_recurrences

Lists the statement files uploaded to Maru in this conversation that have not expired (uploads last an hour), newest first, with their uploadId. Use it after the person picks a file in the upload panel.

list_statement_uploads

List individual transactions in a date range, ordered by date or amount. Use this whenever the user wants to SEE specific transactions rather than a sum: "list my transactions for the first week of March", "what was my first/last transaction this month?", "show me March transactions with their descriptions". Names are enriched client-side. Descriptions are included only when the description-consent toggle is on (otherwise `descriptionsOmitted` is true) — date, amount, category, counterparty and account are always available regardless of consent. Prefer this over biggest_transactions when the user is not asking specifically about the LARGEST transactions.

list_transactions

Turn one projected occurrence of a recurring transaction into a real transaction, as opening a projected row in the app and saving it does: it copies the template, takes the occurrence date, stays linked to its template, and applies any overrides given (e.g. the actual amount). Status defaults as in the app: planned for a future date or a non-cash account, realized otherwise; realized on a non-cash account needs acceptManualRule. Find templateId and date with list_recurrences. Fails if that date is not an occurrence or is already materialized, and with transaction_limit_reached when credits are used up.

materialize_occurrence

The dashboard's income, expense and transfer totals for a year by month, or for one month by day, with the opening balance and the closing balance after each period. Excludes voided rows, recurrence templates and card payments without a bill, as the dashboard does; planned includes projected recurrences. expense is a positive number. For totals over any other date range or by category use aggregate.

monthly_summary

List credit card payments that no imported card bill covers ("Pag. sem fatura" in the app), both the card-side and the checking-side rows. The card-side row is left out of the card's balance until the bill behind it is imported; the checking-side row is real money out and counts. Resolve one by importing the card statement that covers it (import_preview then import), or pair it with transfers_candidates and transfers_link. Read-only.

unmatched_payments

Dry run of a statement import: parse each file, detect its account, and judge every row against the ledger without writing anything. Run it before import, show the person the summary and the open rows, and build the decisions from their answers. Rows the web app commits without asking (new rows, certain duplicates skipped, auto-matches, investment yields) are judged the same way. Rows the web would put in front of the person are returned under `open` with their reasons (match, probable_duplicate, unmatched_payment = a card payment with no bill behind it, "Pag. sem fatura"), candidates and allowed actions, and are LEFT OUT of a commit until decisions cover them. Decisions are an object: {"applyOpeningBalance"?: boolean, "files"?: {"<file name>": {"account"?: "<id|name>", "dueDay"?: 1-31}}, "rows"?: {"<rowId>": {"action"?: "accept"|"link"|"transfer"|"skip", "transactionId"?, "account"?, "category"?, "counterparty"?, "center"?}}}. Row ids are stable for the same file and account. Non-open rows are counted per file; pass all, or offset and limit, to list them.

import_preview

Check an account against the balance its bank statement prints on a date. Stores that balance and date on the account (the account form's statement reconcile fields), so the app's off-by indicator agrees, then reports the ledger balance the app computes for that day (realized, not voided, card payments without a bill excluded), the difference, and the account's transactions within 3 days of the date. The result carries the statement balance and date the account held before, so it can be set back. For a read-only balance use balance_at.

reconcile_balance

Compare a statement file with the ledger for the statement's period: rows missing from Maru, near misses (same date and amount, different description), and rows in Maru the statement lacks, through the same reconcile_statement logic the in-app assistant uses. Also compares the statement's closing balance, when it prints one, with the ledger balance on its last day. Read-only: to bring missing rows in, use import_preview and import.

reconcile_statement

Stop a recurring transaction, as the app's Remove Recurrence does: no more occurrences are projected, the transactions already materialized are kept (detached from it), and the template itself stays as one planned transaction on its first date (delete it with delete_transactions if unwanted). Takes the template id or the id of one of its materialized occurrences. Destructive: the first call returns the plan.

remove_recurrence

Rename a category. Destructive: the old name is overwritten everywhere it shows. The first call returns the plan (old and new name, how many transactions use it) and changes nothing; call again with the confirm token once the person agrees. Same name rules as create_category. Only the tenant owner can rename. Get the id from list_categories.

rename_category

Rename a center. Destructive: the old name is overwritten everywhere it shows. The first call returns the plan (old and new name, how many transactions use it) and changes nothing; call again with the confirm token once the person agrees. Same name rules as create_center. Only the tenant owner can rename. Get the id from list_centers.

rename_center

Rename a counterparty. Destructive: the old name is overwritten everywhere it shows. The first call returns the plan (old and new name, how many transactions use it) and changes nothing; call again with the confirm token once the person agrees. Same name rules as create_counterparty. Only the tenant owner can rename. Get the id from list_counterparties.

rename_counterparty

Substring-search transaction descriptions and notes for a phrase. Privacy-sensitive: requires the user to have enabled the description-consent toggle. If `consentDenied` is true on the response, do NOT guess answers — tell the user how to enable the toggle and offer to continue with the structured tools instead.

search_descriptions

Record the balance a bank statement shows on a date, so the app flags whether the account reconciles (the computed realized balance on that date against this one; account_balances reports the difference). Pass balance null to clear it. Not for cash accounts, as in the app. The result carries the previous statement balance and date, so the change can be set back.

set_account_statement_balance

Set (or clear with null) the category, counterparty and/or center of explicit transactions, as the app's inline edit and bulk bar do. Setting or clearing a category un-voids a voided row, as in the app. On a transfer leg the category is refused (transfers have none) and counterparty/center apply to both legs, as the app's transfer form does. Values are ids or names; createMissing creates a missing name (owner role). Refuses the transfer and voided pseudo-categories: use the transfer operations or void_transactions. The result carries each row's previous labels (and voided flag), so the change can be set back.

set_transaction_labels

Replace the notes of one transaction (null or empty clears them), as the app's form does; allowed on imported rows too. On a transfer leg the notes apply to both legs, as in the app. The result carries the previous notes so they can be put back.

set_transaction_notes

Mark explicit transactions planned or realized, as the status field of the app's form does. Realizing a manual row on a non-cash account, or changing the status of an imported row, breaks Maru's import rule and needs acceptManualRule after the person agreed. Going back to planned resets a manual row's effective date to its date (the app's form does the same); effectiveDate sets it when realizing. Refuses transfer legs (use the transfer operations) and recurrence templates (use materialize_occurrence). The result carries each row's previous status and effective date, so the change can be set back.

set_transaction_status