> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nekt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools

> Explore the tools available to AI agents through the Nekt MCP Server.

The MCP Server provides tools that AI agents can use to interact with your data, files, and pipelines in Nekt.

## Asking about Nekt

### `ask_about_nekt`

Answers questions about the Nekt platform itself — features, configuration, usage, and capabilities. This tool consults Nekt's documentation and does not query your data.

<Tip>
  **Example prompt:** "how do I schedule a Query to run every weekday at 6am?"
</Tip>

## Querying data

### `generate_sql`

Converts a natural language question into a SQL query based on your table schemas. The generated query is scoped to the tables accessible by the token. You can then execute it using the `execute_sql` tool.

<Tip>
  **Example prompt:** "write me a query that returns active users in the last 30 days"
</Tip>

### `get_relevant_tables_ddl`

Discovers which tables are relevant to a given question using semantic search. Returns the full schema (CREATE TABLE DDL) for each matched table — useful for understanding available columns and types before generating SQL.

<Tip>
  **Example prompt:** "which tables should I use to analyze customer churn?"
</Tip>

### `execute_sql`

Executes a SQL query against your data warehouse and returns the results as structured data. Supports pagination for large result sets (up to 1,000 rows per page). The SQL dialect adapts automatically to your cloud — BigQuery for GCP and Nekt Express, Athena for AWS.

<Tip>
  **Example prompt:** "run this query and show me the results: SELECT COUNT(\*) FROM orders WHERE status = 'paid'"
</Tip>

### `get_table_preview`

Returns a small sample (10 rows) from a table to help understand its contents. Useful for inspecting column values, data formats, and categorical fields before writing queries.

<Tip>
  **Example prompt:** "show me a sample of the orders table"
</Tip>

### `list_tables`

Lists tables in the Catalog one page at a time (100 tables per page). Use this when you need a deterministic, complete enumeration of available tables — for example, when browsing the Catalog without a specific question, or when you need a table's `id`. For question-driven discovery, prefer `get_relevant_tables_ddl`.

<Tip>
  **Example prompt:** "list all tables in the trusted layer"
</Tip>

### `get_semantic_context`

Retrieves the most relevant semantic-layer documents for a question using vector search over your business knowledge. Returns curated documentation that explains the business meaning of tables, fields, and metrics, with each document's referenced warehouse resources already resolved. This is the first step of the query workflow — the context it returns grounds `generate_sql` in your organization's own definitions and rules. For semantic context creation, see [Adding context](#adding-context).

<Tip>
  **Example prompt:** "explain how we define monthly recurring revenue"
</Tip>

### `resolve_references`

Follows the references inside a semantic-layer document to pull in related tables, fields, measures, or other context documents that weren't part of the initial match. Use it to traverse the semantic graph when a returned document points to definitions it doesn't fully contain. Returns the resolved entities along with their names, layers, and descriptions.

<Tip>
  **Example prompt:** "how does the revenue metric connect back to the orders table?"
</Tip>

## Browsing files in volumes

### `list_layers`

Lists all data layers (lakehouses) that your token has access to. Returns each layer's ID, name, slug, and description — use this as the starting point when exploring files stored in Nekt volumes.

<Tip>
  **Example prompt:** "what layers do I have access to?"
</Tip>

### `list_volumes`

Lists volumes (file stores) within a layer, or across all layers if no layer is specified. Returns each volume's name, slug, and description. Use this after `list_layers` to discover available file containers.

<Tip>
  **Example prompt:** "what volumes are available in the raw layer?"
</Tip>

### `list_files`

Lists all files stored inside a specific volume. Requires the layer slug and volume slug to scope the results. Returns file metadata including name, type, and size — use this to find the file ID needed to read a file's content.

<Tip>
  **Example prompt:** "list the files in the contracts volume"
</Tip>

### `read_file`

Downloads and returns the content of a file stored in a Nekt volume. Requires the layer slug, volume slug, and file ID. Returns text files as UTF-8 strings and binary files as base64-encoded content. Files larger than 2 MB cannot be returned inline.

<Tip>
  **Example prompt:** "open the latest invoice in the documents volume and summarize it"
</Tip>

## Connecting sources

Sources pull data *into* Nekt from external systems — Shopify, HubSpot, Postgres, and more. The tools below connect a new source through a **draft → publish** flow: create a draft, hand the user a secure browser link to complete OAuth or enter secrets (credentials never pass through the chat), validate the live connection, then finalize.

**The create flow, step by step:**

1. **`list_source_connectors`** / **`get_source_connector`** — find the connector and read its config schema to see required and secret fields.
2. **`create_draft_source`** — create a draft (the connector slug and a description are required; no tables or pipeline yet).
3. **`get_source_setup_link`** — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.
4. **`validate_source_connector_config`** — test the real connection.
5. **`check_connector_validation`** — poll until validation succeeds and the available streams come back.
6. **`complete_source`** — finalize the draft: choose streams, output layer, and trigger. Tables are provisioned and the pipeline is deployed.

### `get_source_connector`

Returns a connector's configuration schema (`config_template`) — every field, which are required, and which are secret — plus a convenience split so you can decide the flow. Connectors with secret fields (OAuth, API keys, passwords) go through the browser deeplink; connectors without secrets can be configured entirely in chat.

<Tip>
  **Example prompt:** "what do I need to connect Postgres as a source?"
</Tip>

### `create_draft_source`

Creates a draft source — the first step of connecting a source. A draft has no provisioned tables and no deployed pipeline; the connector slug and a description are required, so you can start the connection before any secrets exist. For no-secret connectors, you can pass the full config here directly.

<Tip>
  **Example prompt:** "start connecting our Shopify store as a source"
</Tip>

### `get_source_setup_link`

Mints a time-limited (24h) deeplink for a draft source so the user can complete OAuth or enter secret values in the browser — secrets never pass through the chat. Present the link and wait for the user to finish before validating; the token auto-invalidates once the source leaves draft.

<Tip>
  **Example prompt:** "give me the link to enter the Shopify credentials"
</Tip>

### `validate_source_connector_config`

Tests the connector configuration by actually connecting to the external system, catching bad credentials or wrong hosts before the source is finalized. For drafts set up via the deeplink, it re-validates against the config stored on the backend, so secrets never round-trip through the chat. Returns a validation ID to poll.

<Tip>
  **Example prompt:** "check that the Shopify connection works"
</Tip>

### `check_connector_validation`

Polls a validation job until it finishes. On success, it returns the available **streams** — the tables/objects the source can pull, each with its supported sync types, fields, primary keys, and replication keys. Present these so the user can choose which streams to sync before completing the source.

<Tip>
  **Example prompt:** "which tables can I pull from this source?"
</Tip>

### `complete_source`

Finalizes a draft source. Requires a description, an output layer, at least one stream, and a trigger (`manual`, `cron`, or `event`). Each stream specifies a destination table name and a sync type — `INCREMENTAL` (append new/changed rows) or `FULL_SYNC` (replace all). Completion is one-way: it provisions the warehouse tables and deploys the extraction pipeline.

<Tip>
  **Example prompt:** "pull the orders and customers streams into the raw layer and sync them daily at 6am"
</Tip>

## Browsing and managing sources

### `list_sources`

Lists connected sources in your workspace, with filters for free-text search, connector type, status, and archived state. Use it to see what's already connected or to find a source by name.

<Tip>
  **Example prompt:** "show me all my connected sources"
</Tip>

### `get_source_details`

Returns the full detail of a single source by slug, including its streams and triggers. Configuration values are redacted for security.

<Tip>
  **Example prompt:** "what streams is the Shopify source pulling?"
</Tip>

### `list_source_connectors`

Lists the connector types you can connect as a source, returning each one's slug and metadata. Use it to discover the slug needed to start a draft.

<Tip>
  **Example prompt:** "what sources can I connect to Nekt?"
</Tip>

### `update_source_trigger`

Changes the trigger of an already-live source — `manual`, `cron` (a schedule), or `event` (run when upstream pipelines finish).

<Tip>
  **Example prompt:** "run the Shopify source every weekday at 7am instead"
</Tip>

### `update_source_streams`

Adds new streams or edits which streams a live source pulls, applied in place without a redeploy. It is non-destructive — it never removes streams or drops tables; to stop a stream, disable it.

<Tip>
  **Example prompt:** "also start pulling the products stream from Shopify"
</Tip>

### `run_source`

Triggers an extraction run of a live source on demand, optionally as a full sync or for selected streams. This **consumes credits**, so the assistant confirms before running.

<Tip>
  **Example prompt:** "run the Shopify source now"
</Tip>

## Connecting destinations

Destinations deliver data *out* of Nekt to external systems — Slack, Google Sheets, Postgres, webhooks, ad platforms, and more. New destinations are created through a **draft → publish** flow: create a draft, hand the user a secure browser link to complete OAuth or enter secrets (credentials never pass through the chat), then finalize with the tables to deliver and a trigger. Unlike sources, destinations publish directly — there is no separate validation step.

**The create flow, step by step:**

1. **`list_destination_connectors`** / **`get_destination_connector`** — find the connector and read its config schema to see required and secret fields.
2. **`create_draft_destination`** — create a draft (connector slug and a description; tables optional here).
3. **`get_destination_setup_link`** — for OAuth/secret connectors, hand the user a deeplink to finish setup in the browser.
4. **`complete_destination`** — finalize: choose the tables to deliver and a trigger. The delivery pipeline is deployed.

### `list_destination_connectors`

Lists the connector types you can connect as a destination, returning each one's slug and metadata. Use it to discover the slug needed to start a draft.

<Tip>
  **Example prompt:** "what destinations can I send data to?"
</Tip>

### `get_destination_connector`

Returns a destination connector's configuration schema (`config_template`) — every field, which are required, and which are secret — so you can decide the setup flow. Connectors with secret fields (OAuth, API keys) go through the browser deeplink; connectors without secrets can be configured entirely in chat.

<Tip>
  **Example prompt:** "what do I need to send data to a Postgres destination?"
</Tip>

### `create_draft_destination`

Creates a draft destination — the first step of wiring warehouse tables to an external system. A draft has no deployed delivery pipeline; only the connector slug and a description are required. Input tables are optional here and can be chosen later at completion. For no-secret connectors, you can pass the full config here directly.

<Tip>
  **Example prompt:** "start sending revenue alerts to our #revenue Slack channel"
</Tip>

### `get_destination_setup_link`

Mints a time-limited (24h) deeplink for a draft destination so the user can complete OAuth or enter secret values in the browser — secrets never pass through the chat. The page fills only the connector config, not the tables or trigger.

<Tip>
  **Example prompt:** "give me the link to connect our Slack workspace"
</Tip>

### `complete_destination`

Finalizes a draft destination. Requires the tables to deliver (each with its fields, and optional primary keys or field renames) and a trigger (`manual`, `cron`, or `event`). Destinations publish directly — there is no validation step. Completion is one-way: it deploys the delivery pipeline.

<Tip>
  **Example prompt:** "deliver the daily\_revenue table to Slack every weekday at 9am"
</Tip>

## Browsing and managing destinations

### `list_destinations`

Lists connected destinations in your workspace, with filters for free-text search, connector type, status, tag, and archived state. Use it to see what's already connected or to find a destination by name.

<Tip>
  **Example prompt:** "show me all my destinations"
</Tip>

### `get_destination`

Returns the full detail of a single destination by slug. Configuration values are redacted for security.

<Tip>
  **Example prompt:** "what tables is the Slack destination sending?"
</Tip>

### `run_destination`

Triggers a delivery run of a destination on demand. Fire-and-forget — the assistant confirms first, and run history is available through `list_pipeline_runs` / `get_pipeline_run_logs`.

<Tip>
  **Example prompt:** "send the revenue report to Slack now"
</Tip>

## Creating pipelines

### `create_query`

Deploys a SQL Query as a pipeline in Nekt. Accepts the SQL code, a description, the output layer and table name, and an optional trigger — either a cron schedule or an event trigger that runs the Query when one or more upstream pipelines finish. The pipeline starts in `preparing` status — poll `get_pipeline_status` until it leaves `preparing`, then trigger execution with `run_pipeline` once the user confirms. Optionally, the Query can be created already connected to a GitHub repo: pass the repository full name (and optionally a branch), and Nekt creates, connects, and pushes the first commit in one step. The folder in the repo is always the generated pipeline slug. See [Syncing transformation code to GitHub](#syncing-transformation-code-to-github).

<Tip>
  **Example prompt:** "create a daily Query that aggregates revenue by customer into the trusted layer"
</Tip>

### `create_notebook`

Deploys a Python or PySpark Notebook as a pipeline in Nekt. Accepts the notebook code, a description, the runtime type (`python-base`, `pyspark`, or `python-browser`), optional pip dependencies, and an optional trigger — either a cron schedule or an event trigger that runs the Notebook when one or more upstream pipelines finish. For PySpark notebooks, Spark driver and executor sizing can also be configured. Inputs and outputs are extracted automatically from `nekt.load_table` and `nekt.save_table` calls in the code, so the notebook must use the Nekt SDK for all table I/O. Like `create_query`, the pipeline starts in `preparing` status and follows the same deploy-then-run lifecycle. It can also be created already connected to a GitHub repo: pass the repository full name (and optionally a branch), and Nekt creates, connects, and pushes the first commit in one step. See [Syncing transformation code to GitHub](#syncing-transformation-code-to-github).

<Tip>
  **Example prompt:** "create a PySpark Notebook that joins orders and customers and runs every hour"
</Tip>

### `update_transformation_trigger`

Replaces the trigger of an existing Query or Notebook. Supports three trigger types: `manual` (runs only on demand), `cron` (runs on a schedule, with a cron expression and timezone), and `event` (runs whenever upstream pipelines finish). For event triggers, provide the triggering pipeline slugs and an optional rule — `any` runs the transformation when any of them completes, `all` waits for all of them. Use `list_pipeline_options` to discover the available slugs.

<Tip>
  **Example prompt:** "run the daily\_revenue Query whenever the orders and customers sources finish"
</Tip>

### `list_pipeline_options`

Lists all Sources, Queries, Notebooks, and Destinations available as pipeline options, returning each one's slug, description, and type. Use it to discover the slugs needed to configure an event trigger with `update_transformation_trigger`, or to get an overview of the pipelines in your organization.

<Tip>
  **Example prompt:** "which pipelines can I use to trigger a transformation?"
</Tip>

## Syncing transformation code to GitHub

Query and Notebook code can be mirrored into your own GitHub repository (one GitHub App installation per organization). The repo is a code mirror — a transformation's trigger, output layer, and settings still live in Nekt. There are two paths: create a transformation already connected to a repo (via `create_query` / `create_notebook`), or connect transformations that already exist. Once a transformation is connected, editing its code with `update_query` / `update_notebook` auto-commits the change — no extra parameters needed.

### `list_github_repositories`

Lists the repositories the Nekt GitHub App can write to for your organization. Call it once to discover the repo full name (e.g. `my-org/analytics`) needed when creating or connecting transformations.

<Tip>
  **Example prompt:** "which GitHub repos can Nekt push transformations to?"
</Tip>

### `connect_transformations_to_github`

Connects one or more existing Queries or Notebooks to a GitHub repo, uploading each one's current code as a commit. This is the only way to connect a transformation that already exists — there is no GitHub parameter on the update tools. Connecting overwrites any existing repo binding, so it warns before re-pointing a transformation that's already connected elsewhere.

<Tip>
  **Example prompt:** "sync my daily\_revenue and churn notebooks to the analytics repo"
</Tip>

## Running and monitoring pipelines

### `run_pipeline`

Triggers execution of a deployed Query or Notebook pipeline by slug. Returns immediately without waiting for the run to finish — use `get_pipeline_status` to track progress.

<Tip>
  **Example prompt:** "run the daily\_revenue pipeline"
</Tip>

### `get_pipeline_status`

Returns the current status of any pipeline by slug — Queries and Notebooks created through the MCP Server, or Sources and Destinations configured elsewhere in Nekt. Used to track deployment progress after `create_query` or `create_notebook` (until status leaves `preparing`), and to monitor execution after `run_pipeline` until it reaches a terminal state (`success` or `failed`).

<Tip>
  **Example prompt:** "what's the status of the daily\_revenue pipeline?"
</Tip>

### `list_pipeline_runs`

Lists recent runs of any pipeline by slug — Sources, Queries, Notebooks, or Destinations. Returns a summary for each run including its `id`, `status`, `start` and `end` times, and `trigger_type`. Supports pagination (up to 100 runs per page). Use this to inspect a pipeline's execution history, such as checking for recent failures or confirming that a trigger fired.

<Tip>
  **Example prompt:** "show me the last runs of the daily\_revenue pipeline"
</Tip>

### `get_pipeline_run_logs`

Fetches the logs of a specific run, or of the most recent run when only a pipeline slug is given. Returns the `ERROR`-level entries and, when available, Nekt's AI analysis of the failure — a summary of what happened, the technical details, and a suggested fix. Use this to diagnose a failed run without reading the full log.

<Tip>
  **Example prompt:** "why did the last run of the daily\_revenue pipeline fail?"
</Tip>

## Adding context

### `update_resource_description`

Updates the Description of a resource in your Catalog. Supported `resource_type` values are `layer`, `table`, `field`, `folder`, `volume_file`, and `derived_field`. Returns a preview by default — pass `confirm=True` to apply the change.

When `resource_type` is `derived_field`, the tool first identifies the Query or Notebook that produced the target table (via `list_queries` or `list_notebooks`), then enriches the field Description with structured tags inferred from the transformation code: `@pk`, `@fk <table>.<column>`, `@measure additive|non-additive`, `@attribute`, and `@grain=<period>`. Use this when annotating fact, aggregated, or dimension tables so downstream consumers and AI agents can interpret each column's role.

<Tip>
  **Example prompt:** "I want to add descriptions to this table: sessions\_reviews\_consolidated"
</Tip>

### `create_context_document`

Creates a new semantic-layer context document — reusable business knowledge such as metric definitions, segment logic, or table interpretations that should inform future analyses. Documents support annotations (`@table`, `@field`, `@measure`, and more) that link the prose to specific warehouse resources. Returns a preview by default — pass `confirm=True` to save the document after reviewing it.

<Tip>
  **Example prompt:** "save a definition of net revenue that excludes refunds and chargebacks"
</Tip>

### `update_context_document`

Updates an existing semantic-layer context document when a definition is refined, a segment is added, or business rules change. The full name and content are replaced, so the saved version always reflects the complete document. Returns a preview showing the current versus new content by default — pass `confirm=True` to apply the change.

<Tip>
  **Example prompt:** "update the revenue definition to also exclude partial refunds"
</Tip>

### `delete_context_document`

Soft-deletes a semantic-layer context document so it no longer influences analyses or appears in semantic search. Use it for obsolete, duplicated, or incorrect knowledge — prefer `update_context_document` when a document is merely out of date. Returns a preview of the document to be removed by default — pass `confirm=True` to delete it (there is no undo).

<Tip>
  **Example prompt:** "delete the old churn definition document, it's outdated"
</Tip>