These are the native tools a connected agent sees in tools/list, exactly as the server sends them. Native tool names carry no prefix; a tool named <kind>_<8 hex>_<name> (for example airflow_3f2a91bc_list_dags) comes from a connected integration, not from this list. A tool your tenant’s plan or configuration doesn’t include isn’t listed at all — a name missing here or from your own tools/list means “not available to you,” never “broken.” Every tool runs under your own sign-in (or your service user’s), so rows and objects you can’t see are filtered or refused, and results from two different people can legitimately differ. See Every call runs as you. If your tenant’s plan doesn’t include the MCP server at all, none of this applies: every request to the endpoint is refused, not just a subset of tools. See What your plan gates here.

Quick reference

A read-only tool reads data without changing it. A write tool can create state, issue write access, or change existing state. A destructive write can remove or replace data, access, an app version, or scheduled work. Mixed-action tools carry the most conservative label for any supported action. Your MCP client receives a title and hints for read-only, destructive, repeat-safe and external interactions. These hints help clients choose approval prompts; your permissions still govern every call. run_sql is read-only because writes are refused before execution. workspace_db_list is a write because it can create your personal database. SQL and metric reads over connected sources, and new routine runs, carry the external-interaction hint; tools limited to Dippr do not. “Requires” is the scope your connection needs — beyond that, your own roles and grants decide what you may actually touch or see.

list_integration_kinds

Call list_integration_kinds to see which source kinds your tenant can connect, what each needs, who usually holds the credentials, and a link to its connection form. Google Sheets requires a Google service account and someone with Google Cloud access to set it up. If you need a colleague’s help, an admin can use invite_member with role data_engineer; the colleague enters credentials in the console, never in chat. The list is every source kind this build supports. For anything else, export a CSV and load it into a table, or ask your account team for the source. The optional requested_by input follows the same console-link rules as workspace_status.

workspace_status

Call workspace_status first after signing in. One call shows your tenant’s name, engines, indexing state, visible certified metrics, granted scopes, and relevant console links. On a fresh tenant, the onboarding card offers a link to connect your own source, and sample data when this plane has an engine an admin has not parked, before you try a query. It needs only the scope every connection has, never wakes an engine, and never lists tables or columns (use the browsing tools for that). The optional string input requested_by names the AI client to display on console links when the connection has no client information. Pass claude-desktop, claude-ai, claude-code, codex, or cursor; other values are ignored. It is self-reported and display-only, just like connection client information. It grants no access. An available connection client name takes precedence. When the card leads with create_engine or wake_engine, that step comes first. Otherwise, when it offers two paths, choose one:
  • Try sample data: ask your agent to call add_sample_data. The card lists both required scopes in needs_scope: workspace_db:write query_engines:execute_sql. The second scope lets the tool check that the sample is ready. See Sample data.
  • Connect your own source: open the connect_source entry’s console_url. Enter credentials in the console; they never pass through the chat.
An agent that works in a terminal with dip offers one next step it can run instead: dip integration create, with the credential on stdin, or dip db load for files. You can read the card with only query_engines:list, even when your connection cannot add sample data. An offered action does not grant its required scopes. All tools still require sign-in; a 401 response asks your MCP client to authenticate. A part this connection can’t read comes back with status: "not_available" and a next_action (for example “reconnect this server and approve semantic:compile”). A part the service couldn’t answer right now comes back as unknown with a reason. Neither is an error: the call still succeeds. If the engine or data-plane state is unknown, onboarding.status is unknown and sources_connected and next are absent; retry as advised instead of treating that result as proof that you have no data. indexing is also unknown when the index can’t say which of its documents belong to this data plane and your tenant has engines in more than one plane. If this connection cannot verify your tenant’s relationship to its data plane, engines_status and indexing are unknown with a reason and retry advice, and workspace.data_plane_id is omitted. Certified metrics, capabilities, and console links remain available. Indexing is off until an admin turns it on for a data plane. workspace_status can’t read that switch, so not_indexed means “off, or on and not crawled yet”; the next_action links to Settings → Search indexing, where you can check. Try: “What’s in this workspace and what can you do here?“

list_engines

Lists your tenant’s query engines: name, power_state, data_plane_id, catalog_count, and which one to pass as the engine argument on every other tool. in_this_plane is true for an engine this connection can query. When exactly one engine is in this connection’s data plane, every other tool lets you omit engine and uses that one — an engine you add in another data plane doesn’t change that — and each result says which engine answered. With several engines in this plane, name one; the error lists only the ones this connection can reach. An engine with in_this_plane false runs in another data plane: connect to that plane’s MCP endpoint to query it. The list is complete and never truncated — an engine missing from it isn’t reachable from this server, so don’t retry a name that doesn’t appear. On a shared data plane, your tenant’s data_plane_id can differ from the shared cluster’s identifier. The tools resolve that relationship automatically: you can omit engine when only one usable engine runs there, and workspace database tools and workspace_status use your tenant’s data on that plane. A verified relationship is reused for up to 15 seconds for your tenant and data plane; unsuccessful checks are retried on the next call. If the relationship cannot be verified, plane-dependent tools return an error; retry when the service is available. workspace_status still returns its other sections, with engines and indexing marked unknown. A stopped engine wakes automatically on the first query against it, which takes about a minute. run_sql and query_metrics don’t hold that first call open: they answer within seconds with status: "waking" (see When the engine is waking). A deactivated engine was parked by an admin and won’t start on demand. Try: “What query engines do I have?”

Browsing your data

Use browse to list the catalogs an engine can see, then the schemas in one, then tables or views, then one table’s columns and types. Set level for every call. For example, browse with {"level":"tables","catalog":"sales"} searches every schema in sales; add "schema":"public" to narrow it. Arguments unrelated to the chosen level are refused. Each level returns its own listing or column fields, plus the engine that answered. Each result carries a sql_ref for the named object, or for the table at level columns. Use a table’s fully qualified, correctly quoted reference verbatim in a FROM clause. Only objects you’re permitted to see are returned; a table you can see may still have individual columns masked when you actually query it, under the same rules that apply everywhere else. Permission to query a table is also permission to find it: with access to one table and nothing else, these tools show that table, its columns, and the schema and catalog that hold it, and nothing else in that schema or catalog. The listing levels mark a result truncated when more rows exist than one response carries. Narrow schemas or tables with contains rather than paging. The engine’s own system catalog isn’t listed by browse at level catalogs — it holds engine internals, not your data. Try: “What tables do I have in the sales catalog?” → “Show me the columns on sales.public.orders.”

Running SQL

Runs one read-only statement and returns the rows. Only SELECT, WITH, SHOW, DESCRIBE, DESC, VALUES and EXPLAIN are accepted — anything that writes (INSERT, UPDATE, DELETE, MERGE, CREATE, DROP, ALTER, GRANT, CALL) is refused before it reaches your engine, and so is EXPLAIN ANALYZE over a write statement, because that would actually execute it. The refusal says which of these happened: a statement that writes, more than one statement in one call, or a statement run_sql doesn’t recognise, such as a misspelt SELEC. All three have the code invalid_argument, and none of them reaches the engine. Values come back exactly as the engine holds them. A timestamp or time keeps its full precision, so a timestamp(6) value ending in .999999 is not rounded into the next second. Each column’s type includes that precision, for example timestamp(6) with time zone. An integer larger than 9007199254740991 (253 − 1) in either direction comes back as a string of its exact digits, such as "9223372036854775807". Most JSON readers would round a number that large, so a string is the only exact form. Smaller integers and double values stay numbers, and a decimal is a string, as Trino sends it. Rows from query_metrics follow the same rules. A filtered result and a whole one look the same, and a masked value is an ordinary value (a salary masked to 0 is a 0), so run_sql and query_metrics also say whether your access policies changed the answer. After the query finishes they read the engine’s own record of it: row_filters_applied is true when a row filter applied to a table the query read, and column_masks_applied is true when a column it read was masked. Both are plain yes/no answers; how many rows were left out is never reported. policy_note puts it in a sentence to pass on, and is absent when nothing applied. When the engine’s record can’t be read, both flags are absent (never false) and policy_note says the answer can’t tell whether anything was withheld. Rows you aren’t permitted to see are filtered or denied by the engine itself, so an Access Denied means exactly that. When your SQL names the denied table in full (catalog.schema.table), the denial names it too, so you know what to ask an admin to grant. It never lists that table’s columns, or a table behind a view that your SQL did not name. The message reads Access Denied: <table> does not exist or you do not have access to it, because a name that doesn’t exist in a table, schema or catalog you can’t read gets the same answer as a real one. A typo in a table you can read still gets Trino’s own “cannot be resolved” error. The refusal’s code is missing_role, and its message_for_user says the platform can’t tell a missing name from a denied one. Check the name with browse first; a name it doesn’t list may still exist. If the name is right, a tenant admin grants access in Settings → Roles. One case reads differently. When your SQL names a table in full and its catalog is a workspace database you can see (your own, a shared one you belong to, or any of them if you’re a data admin) that this engine hasn’t mounted yet, the refusal’s code is precondition. It says the database exists and is waiting to be mounted, that this isn’t a permissions problem, and what to do next: the same reason workspace_db_list gives as catalog_reason. A grant won’t change it; wait and run the query again. browse and query_metrics answer the same way. A database you can’t see keeps the Access Denied answer above, so the refusal never confirms that someone else’s database exists. Telling the two apart takes a lookup of the workspace databases you can see, which needs the metadata:read scope on top of query_engines:execute_sql. A connection or API key without metadata:read gets the Access Denied answer and missing_role for its own unmounted database too.

Cancelling a query

Each SQL tool call has a default 50-second limit; exceeding it returns a JSON refusal with code: "invalid_argument", query_id (when the engine assigned one), and cancel. With cancel: "canceled", the engine confirmed cancellation. With cancel: "unknown", it may still be running: call cancel_query with that query_id and the same engine. Make the query cheaper before running it again; never resend it unchanged. If your AI tool disconnects while a query runs, the server asks the engine to cancel the query too. cancel_query requires query_id; engine is optional when this data plane has only one engine. It returns canceled, already_finished, or not_running. The engine enforces ownership: you can cancel your own queries; a tenant admin can cancel anyone’s. not_running means the engine doesn’t know the query: it ended long ago, the engine restarted, or it ran on another engine. An engine that is stopped or still starting answers with a retryable refusal instead.

When the engine is waking

If your engine has scaled to zero, the first run_sql or query_metrics call starts it and answers within a few seconds with no rows. You do not need to wait through the cold start:
Nothing ran. Your agent tells you the engine is starting, waits retry_after_seconds, and makes the same call again; once the engine is up the call returns rows as usual, with no status field. A result with rows never carries status. browse still waits through the wake and answers once the engine is up. If the engine is still unavailable after five minutes, check its status and recovery logs before trying again. This is the only way to run a statement directly against your tenant’s connected data. There’s no write equivalent: writing anywhere through this tool always fails, by design — see Workspace database tools for the actual write path. Try: “Run SELECT count(*) FROM sales.public.orders.”

Search tools

Both search tools only appear when your tenant’s plan includes the search feature. See Entitlements.
search_metadata searches catalogs, schemas, tables, views, columns, semantic models and their metrics, verified queries, business concepts, and every comment on any of them — by meaning or keyword, across every catalog at once. Your role must hold Catalogs → Read. A semantic_model or metric hit carries certification_status (draft, proposed, certified or deprecated) — every status is indexed, not only certified ones, so check it before calling query_metrics, which compiles only certified definitions and refuses anything else. A metric hit whose certification_status is certified means the number you’re looking for is already certified — pass its metric_name to query_metrics rather than re-deriving it in SQL. A verified_query hit’s name and comment carry the question and metric names your tenant uses; no MCP lookup takes verified_query_id. A concept hit is your tenant’s own word for something — read it before choosing tables, since it’s the definition your answer has to match. This reads a cached index, so it never wakes a stopped engine, and it can lag: an object created in the last few minutes may not show up yet. An empty result with an empty last_indexed_at means your tenant hasn’t been indexed at all, not that nothing matched. Results are filtered to what you’re allowed to see. result_count is how many results came back, all of them visible to you. withheld is true when some matches were left out because you don’t have access to them. It never says how many or which ones, and it’s the cue to ask whoever manages access in your organization rather than to conclude the data doesn’t exist. It covers only the matches this search looked at, so false doesn’t guarantee there are no restricted matches further down. An empty, non-withheld result can carry a hint — a next step, offered only when the index’s own state makes staleness plausible (never on an ordinary non-match, which returns zero results too, and never when withheld is true: access, not staleness, already explains that empty result). It asks you to have a workspace admin run dip crawl start when your tenant, or one of its engines, has never been indexed — dip crawl start/dip crawl status need the data_admin role, which a caller running search_metadata need not hold. When an engine’s applied catalogs differ from what this index serves (the same catalog_set_differs dip crawl status reports — the state a just-added data source can be in briefly), it points an admin at dip crawl status for the reason rather than promising dip crawl start alone will fix it: an ordinary stale crawl is, but content pending a catalog apply needs that applied first. When indexing is switched off for an engine’s data plane, it says so and asks an admin to turn it on under Settings → Search indexing rather than recommending a crawl the workspace would refuse. It also names an engine whose crawl is still in progress, whose last crawl failed (saying whether an earlier index is still serving, or whether that engine has never completed a crawl), or whose last crawl could not read some catalogs. It gives only a count of those catalogs, never their names. hint is absent when none of this applies to a CURRENT, successfully-checked index — but when the index’s own state genuinely could not be checked (the status read itself failed), hint is still present: a generic, conditional suggestion to check dip crawl status/dip crawl start rather than a confirmed diagnosis. search_queries searches the history of statements your tenant has actually run — each result is one distinct query shape’s newest execution, so a query run ten thousand times appears once. query (required, natural language or a SQL fragment) and limit (default 20, maximum 100) are its only arguments. History is retained for a bounded window, and state on a result matters — a FAILED match means the shape was tried, not that it worked. It searches only the queries you ran unless you hold the tenant-audit permission, which widens it to the whole tenant; withheld is true when the results were narrowed to your own. Use each hit’s user_display (or user when absent) to identify who ran it. This works on a shared data plane too. Members without tenant-audit permission cannot find or read your queries through search_queries or get_query. Try: “Has anyone already written a query for daily revenue by region?”

Document tools

Document tools let you search and read documents available to your signed-in account. They appear only when document search is set up for your deployment and your tenant holds the unstructured_data entitlement. When the entitlement is off, or Dippr cannot confirm it at that moment, neither tool is listed and calling one by name is refused with an error naming unstructured_data; when the entitlement is off, the refusal is precondition. A tenant admin asks Dippr (their Dippr contact or support) to enable Documents; every other tool keeps working. The check runs again on every list and every call, so a connection that stays open stops seeing the tools shortly after the entitlement is removed (the decision is cached for up to 30 seconds). Both tools require query_engines:execute_sql. If your account is not set up for this tenant’s documents, both tools return missing_role. Dippr sets up document access per person when a tenant admin asks (their Dippr contact or support); say which documents or folders you need. Retrying will not help. not_found does not reveal why the read failed. Its message_for_user says: “That document was not found in the documents you can access.” Its next_action tells the agent not to list possible causes (changed, moved, removed or access) or ask the person to check access. Report only searches and reads actually completed; earlier snippets do not confirm current terms. If the MCP tools are not loaded in your agent session or the client cannot reach them, use dip doc search "<query>" --json and dip doc get <folder> <doc_id> --json from the terminal. These commands use the same access rules and return the same disclosure flags and refusal fields, including message_for_user and next_action. See Documents in the CLI. To add a local file to Documents, use dip doc upload <file> --folder <name> from a terminal with your dip login session: a chat client cannot hand MCP a local file. The upload is shared only with you. You can share it yourself in the console: open Documents, choose the folder, then choose Share… from the file’s row menu. No admin is needed. Others who can read the folder can find it after you share it. search_documents takes a required query of 1 to 2,000 characters, an optional list of up to 20 folders, an optional limit from 1 to 50 (default 10) and an optional explain boolean. It returns matching hits with everything needed to cite them: title, folder, doc_id, page, section_path, source_ref and snippet, the matched passage (and low_confidence, below). Cite a hit by its title and page. The result note scopes negative claims to the searches performed and documents you can access; hits do not establish which other documents exist. Pass a hit’s folder and doc_id to get_document to read its chunks; max_chunks is optional, from 1 to 200 (default 50). Search hits and document reads return an opaque revision when source identity is fully recorded. Pass it as expected_revision to get_document to read the revision you observed. If the document changed, was removed or is no longer accessible, the pinned read returns not_found without returning replacement content. Omitting the argument reads the latest accessible revision. Access or metadata changes and re-ingestion can also invalidate a token, including re-ingestion of identical content when it advances the authority revision. After a pinned read is refused, the agent must not retry by dropping the pin. It must report unverified evidence or search again and pass the newly returned revision as expected_revision. The server enforces this for the rest of the MCP session: a later get_document call for that document without expected_revision that would have returned content returns precondition instead, naming the document’s current revision; pinning that revision explicitly reads it. If the unpinned read itself is refused (for example not_found), that refusal is returned unchanged. Other documents, and a new MCP session, are unaffected. A session that has many pinned reads refused reads every document only with expected_revision until it ends. If the document is absent, the revision is unchanged or the new pinned read refuses, stop and report that the current terms remain unverified. A refusal does not reveal whether the document changed, was removed or became inaccessible; do not infer which happened or confirm current terms from the earlier snippet. The token identifies an observed revision; use the document’s own dates to establish when its terms apply. Older indexed documents and image-only results can still be read without a token. If a token is absent, the agent must state that it could not pin that evidence. Normal ingestion or an operator’s content-hash backfill enables revision tokens for text documents. Image-only evidence currently supports latest reads without revision pinning. For questions combining documents and tables, your agent selects the sources needed. It can use get_ontology and ontology_query to resolve business concepts and model bindings, then query_metrics for certified measures or run_sql for other data. A record and document need an evidenced identifier or declared document reference to be linked; similar names are not enough. Answers should retain both query receipts and document citations, identify conflicting evidence and state limits from hidden, truncated or low-confidence results. Search hits provide evidence rather than a complete population for document counts. Document search redacts email addresses, phone numbers, card numbers, SSNs and API keys before returning text. IBANs are also redacted when their country code, country-specific length and mod-97 checksum are valid, with or without whitespace and regardless of letter case. Redaction can also cover adjacent words. Ordinary codes that fail these checks stay visible. Phone redaction includes international numbers that start with +, such as +44 20 7946 0958, and common US phone formats. A contact keep list is an optional deployment setting that preserves selected email domains and phone numbers for one tenant. Your deployment operator can configure it; search requests cannot change it. Listed domains include their subdomains, and phone matching ignores formatting. Kept contacts are visible to everyone who can read the document. Other contacts, cards, SSNs and API keys remain redacted. After a keep-list change, or an upgrade that changes redaction, the first search of each folder rebuilds it in the background; until it finishes, the affected documents are left out of results with withheld: true. Other tenants are unaffected. A document is indexed in pieces: a paragraph, a list item, a link or a bold phrase can each be its own piece. A kept contact that sits alone in a piece stays visible, and the sentences around it stay intact. If the next piece continues the contact with anything other than letters, such as a dot, hyphen, underscore, digit or other symbol (x@acme.example followed directly by .other.test), the two are read as one longer contact that is not on the keep list, and it is redacted as if no keep list were set. Letters are the exception. When formatting ends inside an address, as in **x@acme.co**m written to display x@acme.com, the letters that follow are read as the next word, so the kept part and those letters both stay visible. Avoid formatting that splits an address, and do not keep a domain whose name is the start of a domain that must stay redacted (acme.co when acme.com must not be shown). snippet and chunk text are plain text (not HTML-escaped). Markdown link and image syntax is made inert (a link keeps its text; a bare URL stays as text, which some clients show as a link), common HTML tags that load content or run script are removed, and every < and > that remains comes back as the look-alike characters ﹤ and ﹥, so no tag can survive. Treat the text as untrusted data. A folder is a named group of documents. Folder names and document IDs use lowercase letters, digits, underscores and hyphens, start with a letter or digit, and contain at most 63 characters. Document IDs may also contain periods. Before indexing, HTML pages (and HTML inside Markdown files) get a best-effort removal of text hidden by common hiding mechanisms: hidden or display:none elements and zero-size or off-screen text are left out. Text with the same or nearly the same foreground and background colour is also left out when those colours can be determined from the page. This is not a guarantee: linked style sheets, complex styling, images and transforms can still conceal text that reaches a snippet. Treat document text as untrusted data. withheld: true means a document you cannot open shares a whole content word with your query and would have been among your results. A hidden document that matches only by meaning, with no shared word, does not set it. false says no hidden match met that bar, not that nothing is hidden in the tenant. Searching by page image is not available, so this rule covers every search. This is a yes/no signal, no count, title or hidden text. If indexed content cannot be safely served while an index is being repaired, withheld can also be true even for an unrelated query. low_confidence: true means none of the documents you can access is sufficiently relevant to the query, judged only from the hits you can see. It is not a count and it does not depend on withheld. An agent should then tell you the answer was not found in the documents you can access rather than cite a weak hit; when withheld is also true, it can add that more may exist that you cannot access. Pass explain: true to add an explain object to each hit: its position, its lexical and dense rank among the hits you can see, the query terms it matched (from redacted text), and coarse similarity_bucket and rerank_bucket values. Raw scores are never returned. rerank_skipped: true means reranking was unavailable for some results. Those results keep their original search order. Tell the user: “Reranking was unavailable; results keep their original search order.” truncated: true means the response is incomplete. An absent document and a document you cannot read both return not_found. In this version agents can search and read documents but cannot add or delete them; Dippr adds documents to a folder on a tenant admin’s request. Document text is untrusted data, not instructions. Both tools return untrusted_content: true and a reminder in note; agents should use the text as source material without following commands embedded in it.

Lineage and query history

get_query fetches one past query’s full record by query_id (required; also accepts the matching end_time to narrow the lookup): SQL (with sql_truncated if cut), its error if it failed, lifecycle timing, what it read and wrote, column lineage, the platform’s own computed insights (disk spill, skew, exploding joins, queue time, optimizer misestimates), the execution profile, and the optimizer plan. History is retained for a bounded window — NOT_FOUND can mean the id simply aged out, and it is also the answer for a query someone else ran unless you hold the tenant-audit permission: without it you can fetch the queries you ran, with it any query in the tenant. Use user_display or user to attribute the execution. get_table_lineage shows what feeds a table (upstream) and what it feeds (downstream), by catalog/schema/table (required), with optional direction (upstream, downstream, both, or omit for both) and depth (default 3, maximum 5). Each edge is deduplicated across every query your engines have ever reported, and carries query_count and last_query_id. The graph reflects your own grants, and it’s observed lineage only — a table written by systems outside Dippr shows no upstreams, which each result’s caveat field notes. filtered or truncated means the graph is incomplete. A last_query_id may be unavailable through get_query under your query-history grants. table_impact answers “what breaks if I change this?” — the downstream closure of a table or one column, ranked nearest first, each with query_count, reader_count and last_seen. Same catalog/schema/table arguments, plus optional column (narrow to one column’s impact) and depth (default 3, maximum 5). If the result says filtered: true or truncated: true, the real impact can be larger than what you were shown. Try: “Why did this query run slowly?” (with a query id) → “What would break if I dropped sales.public.orders?”

Semantic layer tools

Each model, concept and workspace database these tools return carries a console_url that opens it in the console (workspace databases link to the Databases page). A link only opens the page; what you can do there is decided by your roles in the console.
These four tools only appear when your tenant’s plan includes the semantic layer. See Entitlements.
list_semantic_models lists your certified metric models — each one names the table it computes over and the measures, metrics and dimensions defined on it, already qualified the way query_metrics expects (orders.revenue). Only certified models are listed by default; pass include_drafts to also see ones still being authored (they can’t be queried). If a result says metrics_filtered: true, at least one model defines metrics you can’t see — that’s not the same as your tenant having no metric for the question. get_semantic_model reads one model in full — every measure, metric and dimension, who owns it, who certified it and when, and example_queries with their status. Replay only examples marked verified. Address it by name (the qualifier in a metric name — orders for orders.revenue) or id. query_metrics computes certified metrics and returns rows, with the compiled SQL alongside them so you can see how the number was produced: You’re running as yourself: a row you aren’t permitted to see produces Access Denied, never a smaller number. metric_columns in the response maps each metric you asked for to the column it came back as. Use that to label a number, not the raw column name. Against a scaled-to-zero engine it answers status: "waking" with the compiled SQL and no rows, exactly as run_sql does. See When the engine is waking. suggest_metric proposes a new metric definition or a verified query into your tenant’s review queue. It changes no definition and certifies nothing — certification is always a human decision. What you get back is a suggestion id and queue status; report it as something for a steward to review, never as a metric your tenant now has. A metric proposal names an existing model. If your tenant has no semantic model yet, the refusal and the certified_metrics next step in workspace_status say to create one first (dip semantic create --file <file>, or the Semantic layer page in the console), then propose the metric. If the only model is a draft that has not been certified yet, the next step says to propose on it rather than create another. You can submit both kinds of suggestion when your tenant uses a shared data plane, with the same semantic:suggest scope and access to the models your proposal uses. The returned review_hint links to the review queue for the submitted suggestion when a console link is available. A link can name your AI client and open a focused view. The focused task completes when you accept or dismiss that suggestion; reviewing another suggestion leaves it open. Your usual sign-in and role permissions still apply. As with workspace_status, the optional string input requested_by supplies the client id only when the connection has no client information. It accepts claude-desktop, claude-ai, claude-code, codex, or cursor and ignores other values. This attribution is self-reported and display-only, just like connection client information. kind accepts metric or verified_query. A proposed metric’s type accepts simple, ratio, derived, cumulative, or conversion; time grains, filter operators, connectives, period aggregations (first, last, average), and conversion calculations (conversions, conversion_rate) are checked by the semantic parser after case and surrounding spaces are normalized. Optional vocabulary fields may be explicitly empty. Try: “What’s our certified definition of revenue?” → “What was revenue last month, by region?” → “That was worth keeping — propose it as a verified query.”

Business vocabulary tools

These two ride the same entitlement as the semantic layer above.
get_ontology reads your business vocabulary as a map: the named concepts your tenant has defined (Customer, Order, Subscription, Churn) and the relationships a person declared between them. Each concept carries its status (only certified is signed off), what it means, and how many bindings to real models you’re permitted to see. It carries no table names on purpose — for that, use ontology_query. filtered means concepts or relationships were withheld. ontology_query starts from one concept (concept, by name, or concept_id) and returns its neighbourhood in one call: nearby concepts, the relationships among them, and the semantic models and tables those concepts are bound to. include_metrics also returns the names of metrics those models publish. max_hops requests how far to walk; the server caps it, and truncated says when the walk stopped at that cap rather than at the edge of what’s known. Every edge here was declared by a person — nothing is inferred. filtered means a concept, edge, binding or metric was withheld, so the whole result may be incomplete. Try: “What do we mean by Churn?” → “What affects Churn, and what tables realize that?” Reading the business vocabulary needs the analyst role or higher, the same as in the console and dip ontology (see the roles matrix). With only viewer, both tools answer “Your role in this workspace doesn’t allow reading the business vocabulary (concepts).” The fix is to ask a workspace admin to give you the analyst role (or a custom role that can read concepts) in Settings → Users.

Workspace database tools

Workspace database tools only appear when your tenant’s plan includes workspace databases. See Entitlements.
A workspace database is a scratch database in the tenant that you own or can access through sharing. Use it for a spreadsheet, a working table, or the output of an analysis. It’s separate from run_sql, which only ever reads your tenant’s shared, governed data. workspace_db_list lists the workspace databases you can reach, with their tables and row counts, optionally narrowed to one database (by name or id). Each table carries a sql_ref, the fully qualified, quoted reference to use verbatim in run_sql, in the same form browse returns. The list reflects what this connection can see on this data plane, so an empty result means none is visible here, which is not always the same as none existing. If you expected to see one, you may be connected to a different data plane’s endpoint than the one your database lives on. If you hold workspace_db:write and none is found, calling this creates your personal one automatically; without that scope it returns an empty list and a note explaining both. Write tools use your default personal database with workspace_db:write alone. If you name a database explicitly, its control-plane lookup also needs metadata:read: request both by name on an OAuth client or mint a workspace API key with both (the query_engines:list connection floor is already part of any MCP connection; add query_engines:execute_sql only to also run workspace_db_list). The key runs as the service user it was minted for, so it works with that service user’s databases. A Data admin or Account admin sees every workspace database on this data plane, including ones they don’t own; see Administrators. For a database the admin isn’t a member of, the entry is for management only: its tables list is empty and tables_error says why, and the write tools refuse it. When the plane can’t read a database’s tables for any other reason, the entry is still returned and tables_error says so in a fixed sentence; the underlying error stays in the plane’s server logs. The owner of a shared database can invite the admin to write to it; a personal database stays its owner’s alone. run_sql reads a workspace database live under its catalog, so a row written through these tools is in the next query’s result. The one wait is once per database: when it first becomes ready, the engines on its data plane have to mount its catalog, and apply_pending is true until they have. Read dip db status (name a shared database), or workspace_db_list through MCP, and follow the catalog reason. Before any engine has assigned a catalog name, check the engines on this connection’s data plane and reuse one if it exists. If none exists, the recovery step tells you to create one when your role allows it, or ask a tenant admin when it does not. When your permissions cannot be checked, the step names the permission needed without claiming you have it. When your role cannot apply engine catalogs, catalog_reason names the wait and asks a tenant admin instead of giving you the apply command. While catalog_mount_in_progress is true, the engine is mounting catalogs: check again in about a minute. If no restart is running, check again after a minute; if unchanged, someone who manages the engine can apply its catalogs with your approval. A stopped engine picks up catalogs within about 10 minutes without starting. For a busy engine, relay the admin step and Query engines list link first, then the timing. If another apply is running, check its result first. Applying restarts the engine and fails its running queries. On first use of a database still being created — your personal one, or a named database (including one shared with you) right after it was created — workspace_db_connect, workspace_db_write_sql, and workspace_db_ingest wait up to 90 seconds for it to be ready. If it is still being created after that, the tool asks you to try again in a minute, naming the database when you passed one. workspace_db_connect hands back a ready-to-run connection snippet with a freshly minted, short-lived token already in it, so your own DuckDB (exactly 2.0.0, which dip db duckdb fetches) can attach directly and stream a large file in locally — far faster than sending it row by row. Optional database and label arguments; the token is shown once. workspace_db_write_sql runs one write statement — INSERT, CREATE TABLE, UPDATE, DELETE, ALTER, CREATE SCHEMA — against a workspace database. sql (required, exactly one statement), optional database and max_rows (default 200, for a SELECT or RETURNING). This is where writing actually happens on this surface. For CREATE, ALTER and DROP the result has no columns or rows, next_step says the change is live rather than speaking of rows, and rows_changed is 0 except for a CREATE TABLE … AS SELECT, where it is the number of rows loaded. next_step says the next run_sql sees the write only when an engine on this data plane already serves the database’s catalog. Otherwise, for example in a tenant with no engine yet, it says the rows or the change are saved and that run_sql can read them once an engine has mounted the catalog, with the reason when one is known; workspace_status and workspace_db_list show when that is. The query(), query_table(), json_execute_serialized_sql(), histogram() and histogram_values() table functions are refused here, because they read a table named by a string built when the statement runs. Name the table directly instead. The histogram() aggregate, as in SELECT histogram(amount) FROM sales, still works in a plain SELECT. Inside CREATE TABLE ... AS, INSERT ... SELECT or PIVOT it is refused too, so run the aggregate as a SELECT first. To copy rows that another connected app returned (for example a Jira search in ChatGPT or Claude chat), the tool tells your agent to copy only a complete result (no further pages) of at most 200 small rows, into a new table, check that its count(*) equals the rows it received, and use dip in Claude Code for anything larger, because every row on this copy path passes through the model, including in Claude Code. A qualifying inline result needs no restart. The load-data skill also instructs agents to keep source and pulled_at columns; the tool description alone does not request these columns. There is no numeric byte or per-row size cutoff in this guidance; do not treat 200 large text/blob rows as small. See small complete inline results. workspace_db_upload_url and workspace_db_ingest are the two steps of loading a local Parquet or CSV file. This is the fast path for anything larger than a few thousand rows, instead of thousands of INSERTs. First workspace_db_upload_url (format, either parquet or csv, and an optional database) returns a short-lived, single-object upload_url and an object_key. You PUT the file’s bytes to that URL. Then workspace_db_ingest (object_key, table, and optional database, schema, format, and mode, where mode is create by default, or replace or append) loads it into a table on the server’s own connection. Once an engine has mounted the database’s catalog, the rows are queryable with run_sql as soon as they are loaded, because engines read the database live; until one has (a new database), next_action says to check workspace_db_list again instead. Its result is the end of the upload: From a terminal, dip db load loads a file without this upload: it reads the file on your machine with the DuckDB built into dip. See Load data. If the workspace can’t issue an upload URL, workspace_db_upload_url fails with the code unavailable and the message “File upload is not available on this workspace right now.” Changing the arguments or calling it again doesn’t help. Tell your workspace admin that file upload isn’t available and give them the request_id from the failure. To load the file in the meantime, run dip db load <database> --from <file> --table <table> from a terminal. Leave <database> out to load into your personal database; without a name, dip db load never loads into a shared one. workspace_db_list reports, for every database, catalog and its engine only once an engine has mounted the database; before that it reports catalog_pending: true with the expected_catalog. sql_name is the database’s current SQL name, which the other workspace database tools accept as database. If the database had to take a suffix because another catalog took the original name, the result shows the updated name. For a database whose engine has not mounted it, workspace_db_list also says when the platform declined that engine’s last automatic restart: catalog_reason says so, and auto_apply_reason gives the reason, for example that someone else used the engine in the last 30 minutes. These top-level fields describe the one engine the result reports. When several engines have a name for the database, each entry in engine_catalogs carries its own mounted and, for an engine the platform declined to restart, auto_apply_reason. When your role cannot apply engine catalogs, an engine that has not mounted it also carries next_step: the wait, if available, and asking a tenant admin to apply, never the apply command. workspace_db_share manages read access to a workspace database you own. Set action to: For every action, database is optional and defaults to your personal database. email and recipient are refused when their action does not use them. The recipient must already be a member of your tenant; only share needs the database’s catalog, which exists once the database has started serving. Sharing does not invite someone or grant write access. To invite someone to write, use dip db invite. Try: “List my workspace databases.” → “Give me a way to load this CSV into my workspace database.” → “Query the table I just loaded.” → “Let alex@example.com read it too.”

Plane file tools

A plane file is any file you store in your tenant’s object storage so that you, your agent or a pipeline can read it back later. Nothing opens, parses or loads it, and it belongs to no database. Each file is private to you: another member’s object_ref is reported as not found. file_upload_url (filename, size_bytes, and an optional content_type) returns a short-lived upload_url, the headers to send with it, and an object_ref. You PUT exactly size_bytes bytes to the URL with those headers before it expires (five minutes). The bytes go straight to object storage and never pass through Dippr’s servers. file_download_url takes an object_ref and returns a short-lived download_url for an HTTP GET. file_list returns your files with their object_ref, name, size and time, 1000 per page; pass next_cursor as cursor for the next page. file_delete removes one permanently. These tools need files:write (upload, delete) or files:read (download, list), which are asked for by name; see Upload and download files. An agent connected through OAuth the usual way (Authenticate in your client, or dip mcp install) does not hold these two permissions. Signing in to this server again will not add them unless this client was registered asking for them by name. The tools still appear in its tool list, and a call is refused with missing_scope. A standard connection cannot use the listed file tools. Use dip file list and the other dip file commands in a terminal instead; dip asks you to approve once in the browser if it needs to. The refusal’s message, message_for_user and next_action all name this step for an OAuth connection. For an API-key connection missing a file permission, next_action instead says to use a workspace API key minted with that permission.

Inviting people

invite_member invites a person to your tenant from the chat, the same invitation Settings → Users → Invite creates in the console. Pass email and, optionally, role; without a role the person joins as viewer. Only a tenant admin can invite. Anyone else is refused with missing_role and the message “Only a workspace admin can invite people. Ask an admin, or invite from” followed by your console’s Users page. You can only invite with a role you hold yourself, and a role your tenant doesn’t have is refused with the list of roles it does have. Nobody is invited when a call is refused. Dippr doesn’t email invitations. The result carries invite_url, the one-time link to send to the person yourself, with email, roles, expires_at, and email_sent, which is always false. The link works once and expires. Anyone holding it can join as the person invited, so send it only to them. If they already have a Dippr account, they join when they sign in and accept the invitation. Inviting them again makes a new link, and the earlier one keeps working until it is used or expires. The result also carries agent_prompt, a short line for the person invited to paste into their AI once they have joined, so it reads your tenant’s /agents.md and connects. It names the tenant’s address only, never the invite link, so it is safe to share. A connection made before members:invite was part of the default consent doesn’t hold it, and the call is refused with missing_scope. Reconnect the server and approve the consent screen to add it. Try: “Invite alex@example.com to my workspace as an analyst.”

Publishing an app from chat

app_publish turns a page your AI built into a live Dippr app and returns its link. It is how you publish from Claude or ChatGPT on the web, where there is no terminal for dip app push. Ask your AI: “Publish this as a Dippr app.” The tool publishes the page and installs it, as you, and replies with the app’s address. The app is published to, and installed on, the data plane your connection goes through; an app already installed on another data plane is updated from there. Your connected AI is instructed to use app_publish for sharing. You do not need to install dip or Docker. Builders already using dip can use dip app new instead. Never publish copied rows in a chat artifact, HTML page, file or screenshot; publish queries so each viewer sees only their own rows. A published app is read-only. Its page runs only its own files, it can read only the catalogs, schemas and tables listed in access, and every person who opens it sees only the rows their own access allows. Anyone in your tenant can open the link. The page is app code like any other: it shows each viewer the rows their queries return, so publish only pages you would share; see Publishing your own apps. The page reads data with a helper every published app carries:
What the page can and cannot contain: The page can be at most 3 MiB, and the published app at most 850 KiB compressed. The result has app_url, ready (true once the app serves), state, the app’s version (each publish advances it), updated (true when an existing app was moved to the new version) and an access list in plain words. A new app usually serves within a minute; when ready is false, the link works shortly after. app_publish needs apps:publish_confined, which every connection asks for by default. A connection made before this permission existed lacks it; reconnect the server and approve the consent screen. An API key cannot publish this way: publish with dip app push instead. Only a static, read-only app can be published this way, whatever your role. The tenant checks that, not only the AI’s connection: the registry stores only a static, read-only app for a publish from chat, and installing or updating an app from chat installs only static, read-only versions. To publish an app that runs its own server, use dip app push. Your role must let you publish your own apps, as every built-in role does unless an admin turned it off; see Install and consent.

Git tools

Git tools manage plane-local Git repositories. All seven tools are omitted from tools/list unless Dippr can confirm the plane_git entitlement. A direct call is also refused when the entitlement is absent, so remembering a hidden tool name cannot bypass the check. A platform ref proposal is not a GitHub or GitLab pull request. Tool results repeat that external remotes are independent and are never mirrored or synchronized. Read and write scopes are separate; request both when a workflow needs to inspect a repository before changing it. Try: “Create a repository for our dbt project, branch from main, and open a platform ref proposal.”

When a call is refused

A refused call is an ordinary tool result marked as an error, never a broken connection. Along with the text, it carries these fields: For an OAuth connection, reconnecting is how you approve a new scope. The server can’t send you a link that re-opens your client’s consent screen, because only your client can start that sign-in. Reconnecting adds only the permissions in the default set. When the missing permission is outside it, next_action says that “signing in to this server again will not add” followed by the missing permission and “unless this client was registered asking for it by name”, then names the recovery step. For file permissions, that step is: Use dip file list and the other dip file commands in a terminal instead; dip asks you to approve once in the browser if it needs to. For other permissions outside the default set, it names an API key minted with the permission. For an API-key connection missing a file permission, next_action instead says “use a workspace API key minted with” the missing permission, for example “use a workspace API key minted with files:read”, with a console link when available.

Sample data

add_sample_data adds the sample dataset (historical US avocado prices, 18,249 rows) to your tenant as a read-only catalog. It is the same action as Use sample data on the console’s Overview page, so an agent can give you something to query before you connect any data. It then waits until your query engine serves the new catalog, and returns the catalog name the engine reports and a first query to run with run_sql. Adding it again is safe: the existing sample is reused. Start with workspace_status. If its onboarding card says sources_connected: false, choose from the paths it offers. Sample data is offered only when this connection’s data plane has an engine an admin has not parked; the link to connect your own source is available without an engine. Choose sample data to try a query without entering warehouse credentials. After add_sample_data returns synced, call workspace_status again: onboarding.sources_connected is true, and the next list is absent. Run the sample_query from add_sample_data with run_sql, passing its returned engine. The result’s status tells you what happened: Only what the engine records after the add counts. A pending or error state the engine already had, or a catalog it was already serving, is not reported as this call’s result: the tool waits for the engine’s next catalog sync, within wait_seconds. Adding a sample the engine already serves at the same version needs no restart when its fixed workspace database catalog names and write settings are also unchanged and nothing else needs Apply. It returns synced after checking the catalog and tables, even while someone else is using the engine. After an upgrade, if the tool reports apply_pending for an already-served workspace database, have someone who manages the engine click Apply, then call the tool again (when nothing needs applying). It needs workspace_db:write (to add the sample) and query_engines:execute_sql (to read the catalog back from the engine). A connection without either is refused before anything is added. It appears only when your plan includes workspace databases. From a terminal, dip integration sample does the same. Try: “I have no data yet. Add the sample dataset and show me five rows.”

MCP overview

What the endpoint is and who can connect.

Scopes and consent

What the Requires column above actually authorizes.

Routine investigations

A routine is a repeatable data investigation with a strict instruction and a schedule. When your tenant has the platform runner configured, ask your agent to test an investigation once. On deployments with automatic setup enabled, runner discovery requests the default installation for eligible tenants. Paused runners and recorded removals stay unchanged, though a runner removed before removal tracking can be set up again; an administrator can check setup when no active runner is available. You need an engine in the same data plane. Agents that use the agent skills get the routine workflow from the routines skill. An agent without them, such as claude.ai or Claude Desktop connected through the MCP address, can read the same text with get_guide and topic routines. It needs only query_engines:list. Any other topic returns invalid_argument listing the valid topics. Correct the topic before calling again. Your agent discovers sources, clarifies thresholds and stop rules, runs once, and shows you the result and coverage before saving. Only a successful, complete run can resolve findings from an earlier run. Failed, partial, cancelled or coverage-withheld runs preserve earlier findings. No findings is different from not checked. Saving requires the scheduling feature to be available in your tenant. A routine saved without explicit start stays PENDING until you confirm it in a fresh console session. If scheduling is unavailable, your agent can still show the manual result; it must not say a routine was saved. Only the owner approves a routine’s proposed action. Saving never grants standing approval. The summary, items, evidence and steps stay with the person whose access the run used. Other people can see that the routine ran and its status. Item views for people other than the run owner are coming. Administrator access does not grant access to this content. Automations read data you can read, including your workspace databases and workspace databases shared with you. What they read can be sent to the configured model provider to investigate your instruction. Each person’s run uses that person’s current access, within installation consent and budgets. Scheduled SQL changes require the routine owner’s approval in the console; per-person routines are read-only. Routines use one data plane. Owner-access routines use the owner’s current access within the installation’s consent; per-person routines use each subscriber’s own access. Future permission growth can expand reads; changing consent requires confirmation again. Service-user execution is unavailable. Daily, weekdays and weekly schedules require an explicit local time and IANA timezone; weekly also requires a weekday. Model cost stops are retrospective; step, query, time and token limits are not a reserved dollar cap. A save_routine result includes a console link that opens the saved work under Automations. Without explicit start: true, it remains a pending draft. Explicit start of personal OWNER work follows the verified-person path described below; per-person activation and subscription still require fresh console confirmation. Routine tools use agents:run and routines:read from normal dip login or dip mcp login. For an older or narrowed session, sign in again and reconnect an AI session holding an old token. Sub-daily intervals such as every 30 minutes are unsupported; choose daily, weekdays or weekly explicitly. Every failed routine run carries a stable failure code and a plain-language reason that any viewer of the run can read; the person whose access ran the check also sees the routine’s own message on a second Details: line. dip routine runs and dip routine show include reasons in text and --json output; get_routine_run and list_routine_runs include them, with failure_code, for AI follow-up.

Suggested routine drafts

save_routine accepts an outcome sentence naming the work (one line, at most 200 UTF-8 bytes) and an optional description (at most 2000 bytes). List and get responses include both; Automation names use the outcome. Older unnamed routines use their subject or “Untitled work”. The legacy subject and suggestion_reason strings remain accepted. The subject names what the routine watches and its intent; the reason is one line explaining why it is suggested. Saving without explicit start: true does not activate the routine. dismiss_routine takes routine_id and reason (not_useful, already_covered or other). Only the owner can dismiss a pending draft that has never been activated. restore_routine takes routine_id and returns the owner’s dismissed draft to pending activation. Restoring alone does not start work. Per-person activation and subscription retain fresh console confirmation. list_routines accepts an optional state: pending, pending_activation, active, paused, blocked or dismissed. The default excludes dismissed drafts. The dismissed filter returns only your own drafts, including subject, suggestion_reason and dismissed_reason. Lists contain metadata, never saved instruction text. Your dismissals do not hide suggestions from other people in your tenant. start_routine_suggestions takes engine_id and an optional IANA timezone, and starts Dippr’s built-in routine runner in the background as you, for when you ask Dippr itself to suggest routines rather than your AI. It saves up to three pending drafts owned by you, skipping routines you already have, have pending or dismissed, defaulting to weekdays at 09:00. One run per person at a time; it counts against the routine runner’s daily run limit. get_routine_suggestions takes an optional run_id and returns state (RUNNING, DONE, FAILED or NONE), added_count, incomplete_coverage and failure_reason. incomplete_coverage: true means the run could not read some data, so it may have missed ideas; it is never a count, and nothing about the drafts is hidden from you. Another person’s run reads as not found.

Starting personal routine work

save_routine accepts explicit start, a stable request_id, and may_propose. Omit start for a pending draft. An explicit personal start creates a Started work-log record and requests one immediate check without a console session. The agent generates and retains the request ID across retries. New work is read only by default. set_routine_authority takes routine_id, expected_version and may_propose. It changes proposal permission only. Scheduled SQL changes require the owner’s approval in the console; MCP and dip bearers cannot approve them. Read current metadata and the owner’s work log through get_routine.

Routine report details

A routine receipt can include progress (on_track, needs_you or blocked) and a reason, an assumptions list, and data_freshness per table. These are model reports, not measured execution status or verified facts. Assumptions remain tentative and do not stop work by themselves. A freshness entry identifies the table, timestamp column, newest timestamp reportedly seen and supporting query reference. An empty or missing timestamp means unknown; even a recent value does not prove that the whole source is current. Older reports can omit these fields. Read the receipt with get_routine_run, or use dip routine runs <routine-id> --json and dip routine show <routine-id> --json. The commands include reports keyed by task ID. CLI report content requires agents:run consent in addition to routines:read; a narrowed login keeps metadata and receives a re-consent command for missing report access. Report content uses your own access; an unavailable report is disclosed while operational run metadata remains visible. Other people’s report details remain private. Preserve coverage.withheld when interpreting progress: on_track does not turn a partial report into an all-clear. Re-read relevant rows before describing a reported claim as verified.

Owner work settings

set_routine_budget stores an optional per-work dollar cap using the current expected_version; omission restores inheritance. Effective spend remains the minimum of the configured cap and the installation ceiling. routine_guidance reads owner-private durable corrections when entries is omitted. To replace or delete entries, send the complete map and its expected_version; {} clears it. Save feedback before a separate dismiss or reject action and report each result. Guidance is data, never write approval. See owner guidance.