Tools reference

Ceviche MCP gives your assistant five tools. You never call them yourself: the assistant picks the tool, fills in its inputs from your question, and turns the result into an answer. This page is for anyone who wants to know exactly what the assistant can do, such as an IT reviewer or a curious controller.

Every tool is read-only. None can create, change or delete anything in Ceviche or in any accounting system. Each tool tells the assistant so, and declares itself to the assistant app as read-only, non-destructive and idempotent (calling it twice changes nothing and returns the same data). Each one reads only the team the connection belongs to, with the signed-in person's own permissions.

The MCP also offers one resource, How to show Ceviche results: the same presentation rules whoami returns, for assistants that read resources.

What every answer carries

• When it was read. Every result has an "as of" time. Nothing is cached between calls: each call reads Ceviche at that moment.
• Where it came from. Every result says it came from Ceviche.
• Warnings, when they matter. For example: the list is only part of the results, some bills have no date, the match holds more than one currency, nothing matched, or some text in the records reads like an instruction to an AI. The assistant is told to pass these on.

whoami

Who this connection is, and the starting map. The assistant is told to call it first in every conversation.

Inputs: none.

Returns:

• you: your name, email and role on the team (Admin, Member or Viewer);
• the team's name;
• the assistant app this connection was made from;
• a map of the team's books: how many records of each kind, the dates the bills cover, how many bills have no date, the currencies in use, and the status words with their meanings;
• the house guide: how to show results to you, and Ceviche's colors and type for anything the assistant builds. See How answers look.

If the team's records can't be read through the MCP yet (see Limits), whoami still answers with who you are and which team you reached, and says the records aren't available.

describe

The details of the team's books, one topic at a time. The assistant uses it when whoami's map isn't enough.

Inputs:

• topic (optional). Leave it out for an overview. Or one of:
  • a kind of record (transaction, line, allocation, invoice, approval, adjustment, attachment, entity, vendor, project, deal, member, policy): its fields, its statuses with their meanings, the date it filters on, what its amount means, and example searches;
  • entities, vendors, projects or members: the names on your team, so the assistant can filter by the exact record instead of guessing at a spelling. Lists come 200 names at a time;
  • filters: the whole filter language;
  • aggregate: what can be totalled, and by what.
• cursor (optional): to get the next 200 names of a long list.

search

Find records of any kind.

Inputs:

• query: filters and words, for example kind:transaction date:2026-Q3 vendor:"Harbor Legal LLP". Empty means everything. Up to 1,000 characters. The language is in Search and filters.
• limit (optional): rows per page, 25 by default, 50 at most.
• cursor (optional): to get the next page of the same search.
• detail (optional): concise (the default) gives one line per record; full adds each record's full contents.

Returns:

• the matching records, each with a readable label (for example "Harbor Legal LLP · 30 Jun 2026 · $12,400.00"), its date, amount, status in the app's own words, and a link to the record in Ceviche where there is one;
• how many records matched in total, how many came back, and whether there are more pages;
• totals summed by Ceviche over the whole match, per kind and per currency, not just over the page shown;
• how many records matched everything except a date filter because they have no date;
• the query as Ceviche understood it, and which default rules it applied (voided bills left out, for example).

If nothing matches, the answer says so and tells the assistant to report exactly what was searched, not to widen the dates or amounts on its own.

fetch

One record in full.

Inputs:

• id: a record's ID from an earlier search or fetch. IDs are for the assistant only; it is told never to show them to you.
• include (optional): kinds of linked record to return in full as well, up to 50 of each. For example, lines and splits for a bill.

Returns:

• every field of the record that the MCP shares (see Records and statuses);
• everything linked to it, by kind: for a bill, its lines, splits, approvals, fund invoices, attachments, vendor and entities. Each kind has a count and up to 20 items, or up to 50 when asked for in full;
• for linked kinds that have statuses, the count and sum per status, computed by Ceviche ("28 Held $1,240.00; 11 New $310.50"), so nobody has to count;
• for a split, each entity's share, what the shares should add up to, and whether they tie.

aggregate

The calculator. Every total the assistant gives should come from here or from search's own totals.

Inputs:

• dataset: spend (bill lines), bills, allocations (splits to entities), invoices or approvals;
• where (optional): the same filter language as search, without kind: and sort:;
• group_by (optional): up to three of entity, vendor, month, quarter, year, status, project, account, approver, currency;
• measures (optional): any of sum, count, min, max, avg. Sum and count by default; count always comes back;
• order (optional): by group key (the default), or by a measure, for example biggest first;
• limit (optional): groups per page, 50 by default, 200 at most;
• cursor (optional): the next page of groups.

Returns:

• each group, with its label, count and the measures asked for;
• totals over the whole filter, per currency;
• whether it ties: the groups add up to the totals, and every split adds up to what it splits;
• what was left out and why, with counts and sums (voided bills, excluded lines, bills with no date, and so on);
• for each group, the search that lists the records behind it, so the assistant can drill in.

Details and examples are in Totals and aggregates.

Errors the assistant may see

• A mistake in its own request, such as an unknown filter or a malformed date. The message says what was wrong and what is valid, so the assistant corrects itself and tries again. You usually never see these.
• Records not available on this team. The team's setup isn't covered yet. The assistant is told to tell you, and not to guess. See Troubleshooting.
• A failure reading from Ceviche. The message gives no details and asks the assistant to try again, and to tell you if it keeps failing.