---
title: "Tools Reference"
source: "https://docs.vertesiahq.com/data-platform/tools"
markdown: "https://docs.vertesiahq.com/llms/data-platform/tools.md"
---

# Tools Reference

The Data Platform provides a comprehensive set of tools for AI agents to manage data stores, tables, queries, and dashboards. Tools are organized into categories based on their function.

## Read Tools

These tools are enabled by default and provide read-only access to data stores.

### data_get_schema

Get the schema of a data store including table definitions, columns, and relationships.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `format` | string | No | `'full'` for complete details, `'data'` for AI-optimized summary (default) |

**Returns:** Schema with tables, columns, relationships, and metadata.

### data_list_tables

List all tables in a data store with metadata.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |

**Returns:** Array of tables with column counts and row counts.

### data_list_dashboards

List dashboards in a data store with optional status filtering.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `status` | string | No | Filter by status: `'active'` or `'archived'` |

**Returns:** Array of dashboard summaries.

### data_list_dashboard_versions

List version history for a dashboard.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The ID of the dashboard |
| `limit` | number | No | Maximum versions to return |

**Returns:** Array of version records with timestamps and snapshot names.

## Write Tools

These tools are disabled by default and must be unlocked by skills. They modify data stores.

### data_create_database

Create a new DuckDB database for storing analytical data.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | Yes | Database name (lowercase with underscores) |
| `summary` | string | No | Description of the database purpose |

**Returns:** Created data store with ID.

### data_create_tables

Create one or more tables atomically in a single transaction.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `tables` | array | Yes | Array of table definitions |
| `message` | string | Yes | Commit message for version history |

**Table Definition:**

```json
{
  "name": "customers",
  "description": "Customer information",
  "columns": [
    {
      "name": "id",
      "type": "INTEGER",
      "primary_key": true
    },
    {
      "name": "email",
      "type": "STRING",
      "semantic_type": "email",
      "nullable": false
    }
  ],
  "foreign_keys": [
    {
      "column": "account_id",
      "references_table": "accounts",
      "references_column": "id",
      "on_delete": "CASCADE"
    }
  ]
}
```

**Column Types:** `STRING`, `INTEGER`, `BIGINT`, `FLOAT`, `DOUBLE`, `DECIMAL`, `BOOLEAN`, `DATE`, `TIMESTAMP`, `JSON`

**Semantic Types:** `email`, `phone`, `url`, `currency`, `percentage`, `person_name`, `address`, `country`, `date_iso`, `identifier`

### data_alter_table

Modify an existing table schema. Creates a version snapshot before changes.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `table_name` | string | Yes | The table to alter |
| `add_columns` | array | No | Columns to add |
| `drop_columns` | array | No | Column names to remove |
| `rename_columns` | array | No | Columns to rename (`{from, to}`) |
| `modify_columns` | array | No | Column modifications |

### data_import

Import data into one or more tables atomically. Creates a version snapshot before import.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `tables` | object | Yes | Map of table names to import configs |
| `mode` | string | No | `'append'` (default) or `'replace'` |
| `message` | string | No | Description for version history |

**Import Sources:**

- **inline**: Data provided directly in the `data` field
- **gcs**: Google Cloud Storage path (`gs://bucket/path`)
- **url**: HTTPS URL to file
- **artifact**: Sandbox output file (`out/filename.csv`)

**Example:**

```json
{
  "store_id": "store123",
  "tables": {
    "customers": {
      "source": "inline",
      "data": [
        {"id": 1, "name": "Alice"},
        {"id": 2, "name": "Bob"}
      ]
    },
    "orders": {
      "source": "url",
      "uri": "https://example.com/orders.csv",
      "format": "csv"
    }
  },
  "mode": "append",
  "message": "Initial data import"
}
```

### data_query (Deprecated)

Execute SQL queries against a data store. Prefer using native DuckDB via `execute_shell` for better performance.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `sql` | string | Yes | SQL query to execute |
| `params` | object | No | Query parameters for `{{param}}` placeholders |
| `limit` | number | No | Max rows to return (default: 100, max: 10000) |

## Dashboard Tools

Tools for creating and managing Vega-Lite visualizations.

### data_preview_dashboard

Preview a dashboard without saving. Renders to PNG for iteration.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `query` | string | Yes | SQL query for dashboard data |
| `spec` | object | Yes | Vega-Lite specification |
| `queryLimit` | number | No | Max rows (default: 10000) |
| `queryParameters` | object | No | Default values for `{{param}}` placeholders |
| `scale` | number | No | Scale factor (default: 1, use 2 for retina) |
| `backgroundColor` | string | No | Background color (default: `'#ffffff'`) |

**Returns:** PNG image of the rendered dashboard.

### data_create_dashboard

Create a new saved dashboard. Use `data_preview_dashboard` first to iterate on design.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `name` | string | Yes | Dashboard name (unique within store) |
| `summary` | string | No | Description of the dashboard |
| `query` | string | Yes | SQL query for dashboard data |
| `spec` | object | Yes | Vega-Lite specification |
| `queryLimit` | number | No | Max rows (default: 10000) |
| `queryParameters` | object | No | Default parameter values |

### data_update_dashboard

Update an existing dashboard.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The dashboard to update |
| `name` | string | No | New name |
| `summary` | string | No | New description |
| `query` | string | No | New SQL query |
| `spec` | object | No | New Vega-Lite specification |

### data_render_dashboard

Render a saved dashboard to PNG.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The dashboard to render |
| `queryParameters` | object | No | Override default parameters |
| `scale` | number | No | Scale factor |

### data_snapshot_dashboard

Create a named snapshot of the current dashboard state.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The dashboard to snapshot |
| `name` | string | Yes | Snapshot name |
| `message` | string | No | Description of this snapshot |

### data_promote_dashboard_version

Restore a specific version as the current dashboard state.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The dashboard |
| `version_id` | string | Yes | The version to promote |

### data_set_dashboard_versioning

Enable or disable automatic versioning for a dashboard.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `store_id` | string | Yes | The ID of the data store |
| `dashboard_id` | string | Yes | The dashboard |
| `enabled` | boolean | Yes | Whether versioning is enabled |

## Best Practices

### Atomic Operations

All schema changes and imports are atomic:
- Creating multiple tables happens in a single transaction
- Multi-table imports succeed or fail together
- Rollback on any failure preserves data integrity

### Versioning

- Automatic versions created on schema changes and imports
- Named snapshots protected from 30-day TTL cleanup
- Use snapshots for important milestones
- Rollback available for any version

### Query Optimization

For complex analytics, use native DuckDB via `execute_shell`:

```sql
-- Window functions
SELECT *, ROW_NUMBER() OVER (PARTITION BY category ORDER BY amount DESC) as rank
FROM orders;

-- QUALIFY clause
SELECT * FROM orders
QUALIFY ROW_NUMBER() OVER (PARTITION BY customer_id ORDER BY order_date DESC) = 1;
```

### Dashboard Workflow

1. Test query separately to verify data
2. Use `data_preview_dashboard` to iterate on visualization
3. Verify the preview looks correct
4. Use `data_create_dashboard` to save
5. Use `data_render_dashboard` to generate final output