> For the complete documentation index, see [llms.txt](https://docs.subsalt.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.subsalt.io/retrieving-data/mcp/tools-and-workflow.md).

# Tools and workflow

## Tools and workflow

The Subsalt MCP server exposes a focused set of tools across three components. This page is a reference for each tool and the recommended workflow that ties them together.

#### Schema & metadata

The canonical description of what data exists. Start here to understand the shape of the data before writing any analysis — this metadata describes structure, not sensitive values, so it is always safe to read.

<table><thead><tr><th width="342.76171875">Tool</th><th>Returns</th></tr></thead><tbody><tr><td><code>instructions</code></td><td>The getting-started guide plus the databases available to you. Call this first.</td></tr><tr><td><code>db_list_databases</code></td><td>The databases you can access, with descriptions and whether each is queryable yet.</td></tr><tr><td><code>db_get_database_details(database_id)</code></td><td>A database's description, source connector, queryability, and its tables.</td></tr><tr><td><code>db_list_tables(database_id)</code></td><td>The tables in a database, with names, namespaces, and source connector.</td></tr><tr><td><code>db_get_table_details(database_id, table_id)</code></td><td>A table's columns: types, descriptions, sample values, and foreign keys.</td></tr></tbody></table>

{% hint style="info" %}
**You always write PostgreSQL.** Each database reports a **Source** (Azure, S3, Snowflake, …) — that is provenance only. Both query paths below are PostgreSQL: the synthetic endpoint *is* a Postgres server, and Secure Compute scripts are written in PostgreSQL and transpiled to the source automatically.
{% endhint %}

#### Synthetic data

Every database serves representative **synthetic data** over a standard PostgreSQL interface. Use it to iterate quickly and safely: understand distributions, sanity-check joins and filters, and develop an analysis on data that is safe to look at.

<table><thead><tr><th width="330">Tool</th><th>Returns</th></tr></thead><tbody><tr><td><code>synthetic_get_connection_info(database_id)</code></td><td>The PostgreSQL connection details (host, port, database, username, password) for querying a database's synthetic data directly.</td></tr></tbody></table>

The agent connects **directly** to the returned endpoint with any Postgres client — it does not move result sets back through MCP, which keeps large result sets off the model's context. The password returned is the caller's own time-limited access token, so no separate Subsalt credential is needed. See running-queries.md for more on the query interface and supported SQL.

{% hint style="warning" %}
Synthetic data is statistically representative but is **not** the real data. Treat any numbers from it as approximate — a fast development loop — and confirm the final answer against real data with Secure Compute.
{% endhint %}

#### Secure Compute

When you need a precise answer grounded in the **real** data, the agent submits an analysis script to Secure Compute. The script runs against real data inside an isolated environment and returns only **privacy-banded aggregates**: the result is high-precision yet legally de-identified under HIPAA, and neither the agent nor the user ever sees a sensitive row.

<table><thead><tr><th width="360">Tool</th><th>Returns</th></tr></thead><tbody><tr><td><code>secure_compute_get_capabilities</code></td><td>The metrics you may compute, the column privacy roles they may target, and the banding/suppression rules applied before results leave the environment.</td></tr><tr><td><code>secure_compute_get_script_guide</code></td><td>How to write the script: the data-access and typed-output API, the result shape, and a worked example.</td></tr><tr><td><code>secure_compute_submit_analysis(database_id, script)</code></td><td>Submits a script; returns an analysis ID immediately. The run is asynchronous.</td></tr><tr><td><code>secure_compute_get_analysis(analysis_id)</code></td><td>The status of a submitted analysis.</td></tr><tr><td><code>secure_compute_get_analysis_results(analysis_id)</code></td><td>The privacy-banded results, once the analysis is <code>Complete</code>.</td></tr><tr><td><code>secure_compute_list_analyses</code></td><td>The analyses you have submitted, newest first, with their statuses.</td></tr></tbody></table>

Secure Compute runs asynchronously: submit a script, poll the status, then fetch results once the analysis reaches `Complete`. Compose the script **against the capabilities contract up front** — anything outside the supported metrics or allowed column roles is rejected or suppressed.

{% hint style="warning" %}
Results are coarsened: counts are rounded and small cells are suppressed for privacy purposes.
{% endhint %}

***

#### The standard workflow

These tools are designed to be used in sequence. A typical analyst session looks like this:

1. **Understand the question.** Clarify what the user wants to learn — usually in plain language, not schema or SQL terms.
2. **Explore the schema** with the `db_*` tools to find the databases, tables, and columns relevant to the question.
3. **Iterate on synthetic data.** Get connection info with `synthetic_get_connection_info`, connect directly, and build up the analysis — explore distributions, refine filters and joins, and write the script. This is the fast, safe development loop.
4. **Confirm against the capabilities contract** with `secure_compute_get_capabilities`, adjusting the script so every metric and column it uses is permitted. Read `secure_compute_get_script_guide` and write the script against that API.
5. **Run against real data.** Submit with `secure_compute_submit_analysis`, poll with `secure_compute_get_analysis`, and fetch the banded result with `secure_compute_get_analysis_results`.
6. **Report the de-identified result**, presenting banded values as approximate and explaining that they were computed without exposing any sensitive record.

#### Key points

* **Synthetic ≠ real.** Synthetic data is for exploration and development; Secure Compute is the source of a trustworthy answer.
* **The agent never touches sensitive data.** Only metadata, synthetic data, and privacy-safe aggregates ever leave the environment.
* **Access mirrors your own.** The agent authenticates as you and can only reach the databases you can reach.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.subsalt.io/retrieving-data/mcp/tools-and-workflow.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.