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.

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

data_list_tables

List all tables in a data store with metadata.

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

data_list_dashboards

List dashboards in a data store with optional status filtering.

Returns: Array of dashboard summaries.

data_list_dashboard_versions

List version history for a dashboard.

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.

Returns: Created data store with ID.

data_create_tables

Create one or more tables atomically in a single transaction.

Table Definition:

{
  "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.

data_import

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

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:

{
  "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.

Dashboard Tools

Tools for creating and managing Vega-Lite visualizations.

data_preview_dashboard

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

Returns: PNG image of the rendered dashboard.

data_create_dashboard

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

data_update_dashboard

Update an existing dashboard.

data_render_dashboard

Render a saved dashboard to PNG.

data_snapshot_dashboard

Create a named snapshot of the current dashboard state.

data_promote_dashboard_version

Restore a specific version as the current dashboard state.

data_set_dashboard_versioning

Enable or disable automatic versioning for a dashboard.

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:

-- 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