MCP tool reference

This is every tool sanda's MCP server can offer an assistant. The names, titles, scopes and parameters below are read from the same tool definitions the server runs, so they cannot drift from what a client sees.

How a credential is offered tools

tools/list returns the tools this credential may use, not every tool. A tool is left off the list, and refused if called anyway, when any of these is true:

• The credential does not hold the scope. Each tool needs one scope. A wider scope includes a narrower one, so a credential holding sql:write also gets everything sql:run and query:run give. See scopes.
• The edition does not include it. The sanda search tools (search_documents and every tool needing search:manage) are on Standard and Enterprise.
• The person behind it is no longer allowed. A privileged scope is honoured only while the person who granted it is an owner or admin.
• The workspace is closed. Then only the tools that read remain: asking questions, looking up the docs and seeing connections.

action_status is offered only to a credential that holds a scope one of the held tools needs. See permissions and approvals.

A token created with no extra switches is offered search_fluid, describe_table, run_query, search_documents and search_docs.

Reading an entry

Each entry starts with the tool's name (the string a client sends), then a row of markers: the tool's title, what kind of tool it is, the scope it needs and, where it applies, the editions that include it. The kind comes from the tool's annotations, which a client can use to skip a confirmation prompt or add one:

• Read only means the tool changes nothing, so calling it again is safe.
• Writes means the tool changes something.
• Destructive means the tool can remove or overwrite something, such as taking tables off the map, dropping a view or committing SQL.

The parameter table lists every top-level parameter with its type, whether it is required, and what it means. Where a parameter is an object or a list, its fields are described in the parameter's own text or in the entry's notes.

Limits every tool shares

A tool that cannot answer returns a sentence and isError: true rather than a failure, for example that two tables would fan out or that a column does not exist. An assistant is expected to read it and try again differently.

Resources

sanda also serves two resources for clients that read them. Both need fluid:read, like search_fluid. A credential without it is listed no resources, and reading one is refused the way a tool is, with a step-up challenge for a connected app:

cherry and MCP

cherry, the console's own agent, uses most of these tools too, under the signed-in person's role and the capabilities switched on under Settings · cherry. It is not offered execute_sql, set_intake, append_rows or the tools that manage sanda search, and action_status is for MCP credentials alone. cherry also has tools of its own for building reports, which are never served over MCP. See cherry.

Read the fluid and your data

Find what the workspace has modelled, look closely at a table, ask a question and search the text inside rows.

search_fluid

Search the fluidRead onlyfluid:read

Finds what the workspace has modelled: metrics, dimensions, named filters, tables and columns. An assistant calls it before using any name it has not already seen in the workspace brief or an earlier answer, because a metric found here is the definition the business agreed on.

The answer is text, one line per match. A search that finds nothing says so, which is an answer: try a synonym before concluding the question cannot be asked.

describe_table

Describe a tableRead onlyfluid:read

Describes one table in full: every column with its type, the grain, the primary key, the time column, the metrics and dimensions measured on it and every join it can follow. An assistant calls it before it names a column.

A table that is not on the map is not found, and the answer names the closest tables that are.

run_query

Run a composed queryRead onlyquery:run

Answers a question with rows. The assistant names what it wants by reference (metrics, dimensions, filters, conditions) and sanda composes the SQL, resolves the joins and runs it, so a number means what the workspace says it means. This is the tool for almost every question.

Operators and named periods are listed in filters. The schema marks every key of a condition as required, so send all four: use an empty list for values and an empty string for relative when they do not apply. relative is only for in_range and names a period such as last_month; sanda resolves it in UTC and states the window it used.

{
  "metrics": ["net revenue"],
  "dimensions": ["region", "issue date"],
  "granularity": "month",
  "conditions": [
    { "field": "issue date", "op": "in_range", "values": [], "relative": "last_6_months" }
  ],
  "limit": 10
}

The answer is text: a table of rows, the window any named period resolved to, and the SQL sanda composed. Metrics measured on different tables can be asked for together, and each is counted on its own table, so revenue beside order count counts every order once. Each metric keeps its own condition. Two tables that would fan out if joined come back as a sentence explaining the refusal, not as a wrong number. A column whose name looks like it holds a secret is never returned.

search_documents

Search the text inside the rowsRead onlyquery:runStandard · Enterprise

Finds rows by what their text says, for questions about wording rather than about a number, such as which invoices mention water damage. It searches meaning and words together and answers with rows and never a total.

Every hit carries the value of its table's key column. To turn hits into a number, take those keys and call run_query with a condition on them.

This is a question of the data, so it needs only query:run, and it is offered to any client holding that scope on an edition with sanda search (Standard and Enterprise). If the workspace has no search service yet, a call answers that there is nothing to search. Managing services is a separate, privileged scope (search:manage).

run_sql

Run SQL you wroteRead onlysql:run

Runs one read-only SELECT the assistant wrote itself. It is the fallback for a question run_query cannot express, such as a window function or a cohort. It bypasses the workspace's own definitions, so the number is the assistant's rather than the business's.

Runs through the reader role inside a read-only transaction, returns at most 50 rows and stops after 20 seconds. A column whose name looks like a credential or an identity number is refused, whatever the statement calls it.

A default integration token does not see this tool at all: it is listed only for credentials granted sql:run. cherry is offered it only when its sql capability is switched on under Settings · cherry.

search_docs

Search the sanda docsRead onlyfluid:read

Searches sanda's own documentation at docs.sanda-os.com.au for how the product works and how to do something in it. An assistant calls it for a question about sanda, never for a question about your data, and gives you the link it used.

The answer is text: for each match, the page and section title, the address of the section, and the section's own words. A search that finds nothing says so and points at the docs site.

This reads public pages and nothing of the workspace's data, so it needs only fluid:read, and a call is never held for approval. It makes no model call, so it costs nothing on the AI limit. cherry uses it too, to answer how-to questions with a link.

See and refresh the workspace

Check which connections and warehouses exist, how fresh and how full they are, and start a sync.

list_connections

List connectionsRead onlyworkspace:read

Lists every data connection in the workspace: the system it pulls from, its health, when it last synced, how many rows it has landed, its schedule and where it lands. An assistant uses it to answer whether the data is fresh.

Takes no parameters.

Never returns a credential.

connection_status

One connection, in detailRead onlyworkspace:read

Shows one connection's last ten runs with status, rows, duration and any error text, and the dataset its rows became. While a sync is running it also reports the stage, rows read so far, the average rate and each stream's state.

list_warehouses

List warehousesRead onlyworkspace:read

Lists each warehouse with its storage against its limit, compute, table and row counts, and whether ingest is paused. An assistant uses it before a large load to check how much room is left.

Takes no parameters.

Never returns a connection string.

sync_now

Start a syncWritesworkspace:manage

Starts one connection's sync now instead of waiting for its schedule. The rows land in the background, and connection_status shows how far the run has got.

A sync reads from the source system and lands rows in the warehouse, so it costs compute like any other sync. This is the only tool that drives a connection.

Write the semantic fluid

Put landed tables on the map, define metrics, dimensions, filters and relationships, and review what sanda proposed. Definitions go live at once.

list_warehouse_tables

List tables in the warehouseRead onlyfluid:write

Lists every table that has landed in the warehouse, with its columns, a row estimate and whether it is already on the semantic map. This is the raw layer describe_table cannot see, and the first step before import_tables.

import_tables

Put warehouse tables on the mapWritesfluid:write

Puts landed tables on the semantic map so the fluid can query them. sanda reads each table's shape, publishes a view over the columns chosen and files it under its connector's dataset, then reports the kind, key and time column it guessed and the joins it drew.

Importing a table that is already on the map refreshes it and does not duplicate it. Nothing here changes the rows in the warehouse.

set_table_kind

Mark a table as a fact or a dimensionWritesfluid:write

Says whether a table on the map is a fact or a dimension. Getting this right is what stops a query summing a price list. An assistant calls it after import_tables when sanda's guess was wrong.

retire_tables

Take tables off the mapDestructivefluid:write

Takes tables off the semantic map. The rows in the warehouse are untouched, but every metric, dimension, filter and relationship written against those tables goes with them.

Destructive to the model, not to the data. A well-behaved assistant reads the table names back to the person before calling it. cherry always asks first, whatever its mode.

define

Define something in the fluidWritesfluid:write

Creates or replaces one definition in the fluid, live at once: a metric, dimension, filter, relationship, alias, category or dataset, or a statement of what a table already on the map means.

A definition with the same name replaces the old one, and names are matched without regard to case. The reply names the table the definition landed on and says if an expression uses a column that table does not have.

{
  "kind": "metric",
  "definition": {
    "name": "net revenue",
    "table": "invoices",
    "expression": "sum(total_ex_gst)",
    "format": "currency",
    "synonyms": ["turnover"]
  }
}

list_proposals

List proposals awaiting reviewRead onlyfluid:write

Lists everything sanda's own learning pass has proposed and nobody has signed off: tables, metrics, dimensions, filters and relationships. Proposals are invisible to queries until they are accepted.

Takes no parameters.

review_proposal

Accept or reject a proposalWritesfluid:write

Accepts or rejects one proposal. An accept may carry corrections, so a nearly right proposal is one call. A relationship is decided on both sides together.

Accept a relationship's tables before the relationship.

delete_definition

Delete a definitionDestructivefluid:write

Removes one metric, dimension, filter, mapping, category, dataset or glue definition from the fluid for good. Redefining with define is better than deleting and recreating, because a delete loses the definition's history.

cherry always asks first, whatever its mode.

Load and change warehouse data

Land tables of an agent's own rows, add rows to tables opened for intake, and run one committed SQL statement of its own.

load_rows

Load rows into the warehouseWriteswarehouse:write

Lands a table of an agent's own rows in the warehouse as raw.csv__<table>, through the same loader and storage limit a sync uses. Typical uses are a forecast it computed or a lookup it was given. It cannot touch a table a sync landed.

Send rows: [] with declared types to create an empty table. For more than 10,000 rows, append in batches.

{
  "table": "sales forecast",
  "columns": [{ "name": "month", "type": "date" }, { "name": "forecast", "type": "numeric" }],
  "rows": [["2026-10-01", 125000], ["2026-11-01", 131500]],
  "import": true
}

set_intake

Open or close a table for intakeWriteswarehouse:write

Opens a hand-loaded table for intake, or closes it. While a table is open, credentials holding warehouse:append may add rows to it and do nothing else. Closing leaves the rows and the map as they are.

The shape for a log a person keeps by talking to an assistant: land the table once with load_rows, open it here, then give the person a credential holding only warehouse:append. Not offered to cherry.

append_rows

Add rows to an intake tableWriteswarehouse:append

Adds rows to a table an owner or admin has opened for intake. It only ever appends: it cannot create, replace or delete a table, and a table that is not open refuses.

Send dates as YYYY-MM-DD, numbers as numbers and booleans as true or false, and leave a field null when the value is not known: the warehouse refuses a value a column cannot hold. If the same day is told twice, append a second row and let the workspace's model decide which counts.

This is the one write any member may grant, because its reach is only the tables an owner or admin has opened. Not offered to cherry.

{
  "table": "daily log",
  "rows": [{ "day": "2026-09-30", "steps": 8200, "note": "Long walk" }]
}

execute_sql

Run and commit SQL you wroteDestructivesql:write

Runs one SQL statement the agent wrote on a warehouse, as the warehouse's builder role, and commits it. The builder reads every landing table and writes only in the derived schema. This is the SQL shell held by a machine, and there is no undo.

A sync's landing tables, a published mapping view, the search indexes and sanda's own bookkeeping are out of reach whatever the statement says. A statement that changes rows answers with its command tag and the number of rows touched.

When the workspace asks for approval before an agent acts, a write-mode call is held for an owner or admin and does not run until one approves it. A read call is never held. See permissions and approvals. Not offered to cherry.

Views and procedures

Define, build and tune views, materialized views and procedures in the derived schema of a warehouse.

list_sources

List what a view may be built onRead onlywarehouse:model

Lists every relation in a warehouse that a view may be built on, with columns and types: landing tables, derived objects already defined, and the mapping tables. It is read as the role that would own the view, so it lists exactly what a CREATE will accept.

A published mapping.* view is not listed and cannot be built on. Build on the table behind it.

list_views

List derived views and proceduresRead onlywarehouse:model

Lists every view, materialized view and procedure the workspace has defined in a warehouse's derived schema: its definition, its version, when a materialized view was last built and whether it is on the semantic map.

create_view

Define a view or materialized viewWriteswarehouse:model

Defines a view in the derived schema from one SELECT over anything list_sources names. A materialized view stores its result and is built now, on the workspace's compute. The view goes on the semantic map in the same call unless told not to.

A materialized view's build runs on the workspace's compute and is billed to it, which is why the scope that allows this is privileged. See usage.

refresh_view

Rebuild a materialized viewWriteswarehouse:model

Rebuilds one materialized view now and reports how long it ran and what it cost. An assistant calls it after the tables behind the view have synced.

Runs for up to 55 seconds inside the call. A build that needs longer, up to 14 minutes, belongs on a schedule.

drop_view

Drop a derived objectDestructivewarehouse:model

Drops one view, materialized view or procedure from the derived schema, taking it off the semantic map first. It is refused while another derived view reads it, because sanda never cascades. The definition stays in the history and the rows do not.

When the workspace asks for approval before an agent acts, this call is held for an owner or admin. See permissions and approvals. cherry always asks first, whatever its mode.

create_procedure

Define a procedureWriteswarehouse:model

Defines a procedure in the derived schema: a multi-step transform in plpgsql or SQL that builds, merges or reshapes derived tables, with COMMIT allowed between steps. It runs as the warehouse's builder role.

The builder role may read landing tables, derived objects and the mapping tables, and may create and write only in derived. It cannot write a row anywhere else, whatever the body says. Run it with call_procedure.

call_procedure

Run a procedureWriteswarehouse:model

Runs one procedure now, with its arguments in declared order, and reports how long it ran and what it cost.

Runs for up to 55 seconds inside the call. A run that needs longer belongs on a schedule.

warehouse_advice

What is slowing this warehouse downRead onlywarehouse:model

Reads a warehouse's own statistics and says what is slowing it down or costing it storage: a missing index, a table autovacuum has fallen behind on, stale statistics after a sync, an unused index, storage a rewrite would give back, or a table large enough to partition. It writes nothing.

Each finding carries an id, the figures behind it and the statement sanda would run. A finding with no statement is one sanda will not act on, and it says why. Pass the ids you want acted on to optimise_warehouse.

optimise_warehouse

Apply what the advice foundWriteswarehouse:model

Runs the findings you name by id from warehouse_advice: a vacuum, an analyse, an index created or dropped. sanda re-reads the warehouse first and runs only findings that are still current. It never runs SQL you send it.

Each statement runs on the workspace's compute, is recorded on the run ledger and is billed as the seconds it takes. A finding that would lock a table against readers says so in the advice, so read it before sending its id.

Schedules

Run views and procedures on a clock or after a sync, and read what each run did and cost.

list_schedules

List schedulesRead onlywarehouse:model

Lists every task graph in a warehouse: its steps, its cadence, whether it is paused or has suspended itself after failures, when it next runs and how its last run went.

create_schedule

Schedule a task graphWriteswarehouse:model

Defines a task graph: an ordered list of steps on the warehouse, each a materialized view to refresh or a procedure to call, and when it runs. Steps run in order, and a step is skipped when the one before it failed.

One run has at most 14 minutes, and every run is billed as the seconds its statements executed.

{
  "name": "nightly rebuild",
  "tasks": [{ "refresh": "revenue_by_month" }, { "call": "close_month", "args": ["2026-09-01"] }],
  "cron": "0 18 * * 1-5"
}

That cron is weekdays at 18:00 UTC.

run_now

Run a task graph nowWriteswarehouse:model

Queues one task graph to run now rather than waiting for its schedule. Because the scheduler runs on a 15 minute grid, it starts at the next quarter hour. A graph already queued or running is not queued again.

pause_schedule

Pause or resume a task graphWriteswarehouse:model

Pauses a task graph so nothing fires it (not its schedule, not a sync landing, not run_now), or resumes one that is paused or has suspended itself. Resuming resets its failure count.

run_history

Run historyRead onlywarehouse:model

Shows what ran and what it cost: the recent runs of one task graph with each step's outcome and seconds, or the versions, builds and calls of one derived view or procedure.

Manage sanda search

Create, change, build and remove search services over tables on the map, and estimate what indexing costs first.

list_search_services

List search servicesRead onlysearch:manageStandard · Enterprise

Lists every sanda search service in a warehouse: the table and columns it indexes, how many rows and how large the index is, when it last built and what that cost. It also says whether sanda search is switched on for the workspace at all.

The search tools are available on Standard and Enterprise. Not offered to cherry.

describe_search_service

Describe a search serviceRead onlysearch:manageStandard · Enterprise

Describes one search service in full: its definition and state, every build with the rows it embedded and what it cost, and every version its definition has had. An assistant uses it to find out why a service is broken.

estimate_search_build

Estimate what indexing would costRead onlysearch:manageStandard · Enterprise

Estimates what indexing a table would cost before anything is created: rows, tokens, dollars and how that compares with the workspace's daily AI limit.

create_search_service refuses without confirm: true when a build would use more than half a day's AI limit. This is how to know that in advance.

create_search_service

Create a search serviceWritessearch:manageStandard · Enterprise

Indexes the text of a table so it can be searched by meaning as well as by words. The first build sends the text of the columns named to an embedding model outside Australia and is charged against the workspace's daily AI limit.

sanda search must be switched on by a workspace owner in the console before this works. An agent holding the scope cannot switch it on, because it is a decision about where a business's data may be processed. A column whose name says it holds a secret is refused outright. Not offered to cherry.

update_search_service

Change a search serviceWritessearch:manageStandard · Enterprise

Redefines a search service or changes when it rebuilds. Changing the model, text columns, chunk size, word matching, key or source rebuilds the whole index at the cost of a first build. Changing only the attribute columns, description or cadence costs nothing.

A well-behaved assistant tells the person before it rebuilds a large table. Not offered to cherry.

build_search_service

Index a search service nowWritessearch:manageStandard · Enterprise

Queues an index build now instead of waiting for the service's own trigger. Only rows whose text changed since the last build are sent to the model, so it is cheap on an unchanged table.

This only queues the build. sanda's scheduler runs on a 15 minute grid, and indexing then runs in slices across as many ticks as it takes. Use run_search_build to spend the call indexing now. Not offered to cherry.

run_search_build

Index a search service now, inside this callWritessearch:manageStandard · Enterprise

Queues a build and then spends up to 55 seconds of the call indexing it, so a small index finishes inside the call. It reports what it read, embedded and cost.

An index too large for one call keeps its place and says there is more to do: call again to carry it on, or leave it to the scheduler. This builds an index and does not query one. Use search_documents for that. Not offered to cherry.

drop_search_service

Remove a search serviceDestructivesearch:manageStandard · Enterprise

Removes a search service and deletes its index from the warehouse. Searches against it stop at once, and rebuilding it later costs a full first build. The definition and every build it ran stay on record.

When the workspace asks for approval before an agent acts, this call is held for an owner or admin. See permissions and approvals. Not offered to cherry.

Email reports

Schedule, change, pause, send and remove report deliveries.

list_deliveries

List report deliveriesRead onlyreports:deliver

Lists every report delivery: the report it sends, its cadence, who it goes to, whether it is paused, when it next goes and how its last run went, with each delivery's id. It also names the reports that have no delivery.

Reading deliveries needs the same scope as creating them, because the list is who receives what.

create_delivery

Schedule a report deliveryWritesreports:deliver

Emails a report on a schedule. At each firing sanda asks every block on the report again and sends the answers to the recipients. Email only: Slack and webhook deliveries are set up on the Report schedules page, because their address is a secret.

A workspace may limit which email domains a delivery can go to, and the answer says so when a recipient is outside them. To send a report once, create the delivery, send it with send_delivery, then pause it with pause_delivery.

When the workspace asks for approval before an agent acts, a call naming a recipient outside the domains its members use is held for an owner or admin, because a report emailed to someone cannot be recalled. See permissions and approvals. cherry always asks before an email, whatever its mode.

{
  "report": "Board pack",
  "recipients": ["cfo@example.com.au"],
  "cron": "0 8 * * 1",
  "timezone": "Australia/Sydney"
}

update_delivery

Change a report deliveryWritesreports:deliver

Changes who a delivery goes to, its closing note or when it goes. recipients is the whole new list, so to add someone pass the current recipients with them, and to remove someone leave them out.

Held for approval on the same terms as create_delivery when a recipient is outside the domains the workspace's members use.

send_delivery

Send a report delivery nowWritesreports:deliver

Sends a delivery now, to its recipients, instead of waiting for its schedule. It goes out within a minute or two.

A paused delivery can still be sent by hand. cherry always asks first, whatever its mode.

pause_delivery

Pause or resume a report deliveryWritesreports:deliver

Pauses a delivery so its schedule stops sending it, or resumes a paused one. A resumed delivery next goes at its next firing from now.

delete_delivery

Remove a report deliveryDestructivereports:deliver

Removes a delivery. The report stays, and the record of every run it made stays on the timeline. Only the schedule and its recipients go.

pause_delivery is the way to stop one for a while. cherry always asks first, whatever its mode.

Approvals

Find out what happened to an action the workspace held for a person to approve.

action_status

Check an action waiting for approvalRead onlyany held scope

Reports what happened to an action the workspace held for approval: still waiting, declined, expired, or approved and what the tool answered when it ran. With no id it lists this credential's ten most recent actions.

A credential sees only its own actions. The tool is listed only for credentials that hold a scope a held tool needs (sql:write, warehouse:model, search:manage or reports:deliver), because a credential that can only ask questions never has anything waiting. It is read-only, and it is never held itself.

A well-behaved assistant never tells a person a held action is done until this says it ran. See permissions and approvals.