Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Lightdash MCP Server show me the top 10 customers by revenue"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect Claude, Cursor, and other AI assistants to your Lightdash analytics using the Model Context Protocol (MCP).
A Model Context Protocol (MCP) server for interacting with Lightdash, enabling LLMs to discover data, create charts, and manage dashboards programmatically.
This MCP server provides a comprehensive set of tools for the full data analytics workflow:
Discovery: Explore data catalogs, find tables/explores, and understand schemas
Querying: Execute queries with full filter, metric, and aggregation support
Chart Management: Create, read, update, and delete charts with complex visualizations
Dashboard Management: Build and manage dashboards with tiles, filters, and layouts
Resource Organization: Create and manage spaces for content organization
Related MCP server: Cursor DB MCP Server
Python 3.10+
A Lightdash instance (Cloud or self-hosted)
Lightdash Personal Access Token (obtain from your Lightdash profile settings)
pip install lightdash-mcpuvx lightdash-mcppipx run lightdash-mcpgit clone https://github.com/poddubnyoleg/lightdash_mcp.git
cd lightdash_mcp
pip install .If your Lightdash instance is behind Google Cloud Identity-Aware Proxy (e.g. Cloud Run with --iap), install with the iap extra:
pip install lightdash-mcp[iap]
# or from source
pip install .[iap]Set IAP_ENABLED=true. The server will sign a JWT (audience {LIGHTDASH_URL}/*) via the IAM Credentials API and attach it as Proxy-Authorization: Bearer <jwt> on every request. The Authorization: ApiKey header is preserved for Lightdash.
Both service account credentials and user credentials (Application Default Credentials / ADC) are supported:
Service account credentials (default in Cloud Run, GCE, etc.):
The runtime service account needs roles/iam.serviceAccountTokenCreator on itself
The runtime service account needs roles/iap.httpsResourceAccessor on the Cloud Run service
User credentials (ADC) (e.g. gcloud auth application-default login):
Set IAP_SA to the service account email to impersonate for signing the JWT
The user needs roles/iam.serviceAccountTokenCreator on the target service account
The target service account needs roles/iap.httpsResourceAccessor on the Cloud Run service
The server requires the following environment variables:
Variable | Required | Description | Example |
| ✅ | Your Lightdash Personal Access Token |
|
| ✅ | Base URL of your Lightdash Instance |
|
| ❌ | Cloudflare Access Client ID (if behind CF Access) | - |
| ❌ | Cloudflare Access Client Secret (if behind CF Access) | - |
| ❌ | Default project UUID (falls back to first available project) |
|
| ❌ | Enable Google Cloud IAP authentication ( |
|
| ❌ | Service account email for IAP when using user credentials (ADC) |
|
Log into your Lightdash instance
Go to Settings → Personal Access Tokens
Click Generate new token
Copy the token (starts with ldt_)
Add the following to your claude_desktop_config.json:
{
"mcpServers": {
"lightdash": {
"command": "uvx",
"args": ["lightdash-mcp"],
"env": {
"LIGHTDASH_TOKEN": "ldt_your_token_here",
"LIGHTDASH_URL": "https://app.lightdash.cloud",
"LIGHTDASH_PROJECT_UUID": "your-project-uuid"
}
}
}
}Create or edit .mcp.json in your project root:
{
"mcpServers": {
"lightdash": {
"type": "stdio",
"command": "lightdash-mcp",
"env": {
"LIGHTDASH_URL": "https://your-lightdash-instance.com",
"LIGHTDASH_TOKEN": "ldt_your_token_here",
"LIGHTDASH_PROJECT_UUID": "your-project-uuid"
}
}
}
}Restart Claude Code and run /mcp to verify the server shows as connected.
Note: Don't commit
.mcp.jsonif it contains secrets — add it to.gitignore.
Export the environment variables before running:
export LIGHTDASH_TOKEN="ldt_your_token_here"
export LIGHTDASH_URL="https://app.lightdash.cloud"
lightdash-mcpTool | Description |
| List all available Lightdash projects |
| Get detailed information about a specific project |
| List all available explores/tables in a project |
| Get detailed schema for a specific explore (dimensions, metrics, joins) |
| List all spaces (folders) in the project |
| Get custom metrics defined in the project |
Tool | Description |
| List all saved charts, optionally filtered by name |
| Search for charts by name or description |
| Get complete configuration of a specific chart |
| Create a new saved chart with metric query and visualization config |
| Update an existing chart's configuration (name, description, queries, visualization) |
| Execute a chart's query and retrieve the data |
| Delete a saved chart |
Tool | Description |
| List all dashboards in the project |
| Create a new dashboard (empty or with tiles) |
| Clone an existing dashboard with a new name |
| Get all tiles from a dashboard with optional full config |
| Get complete chart configuration for a specific dashboard tile |
| Get the complete dashboard configuration as code |
| Add a new tile (chart, markdown, or loom) to a dashboard |
| Update tile properties (position, size, content) |
| Rename a dashboard tile |
| Remove a tile from a dashboard |
| Update dashboard-level filters |
| Execute one, multiple, or all tiles on a dashboard concurrently |
Tool | Description |
| Execute a saved chart's query and return data |
| Run queries for dashboard tiles (supports bulk execution) |
| Execute an ad-hoc metric query against any explore |
Tool | Description |
| Create a new space to organize charts and dashboards |
| Delete an empty space |
.
├── pyproject.toml # Package configuration
├── lightdash_mcp/ # Main package
│ ├── __init__.py # Package init
│ ├── server.py # MCP server entry point
│ ├── lightdash_client.py # Lightdash API client
│ └── tools/ # Tool implementations
│ ├── __init__.py # Auto-discovery and tool registry
│ ├── base_tool.py # Base tool interface
│ └── *.py # Individual tool implementations
├── README.md
└── LICENSEThe server automatically discovers and registers tools from the tools/ directory. To add a new tool:
Create a new file in lightdash_mcp/tools/ (e.g., my_new_tool.py)
Define the tool:
from pydantic import BaseModel, Field
from .base_tool import ToolDefinition
from .. import lightdash_client as client
class MyToolInput(BaseModel):
param1: str = Field(..., description="Description of param1")
TOOL_DEFINITION = ToolDefinition(
name="my-new-tool",
description="Description of what this tool does",
input_schema=MyToolInput
)
def run(param1: str) -> dict:
"""Execute the tool logic"""
result = client.get(f"/api/v1/some/endpoint/{param1}")
return resultRestart the server - the tool will be automatically registered
Tools are automatically discovered via tools/__init__.py, which:
Scans the tools/ directory for Python modules
Imports each module (excluding utility modules)
Registers tools by their TOOL_DEFINITION.name
You can test individual tools by importing them:
from tools import tool_registry
# List all registered tools
print(tool_registry.keys())
# Test a specific tool
result = tool_registry['list-projects'].run()
print(result)If you see 401 Unauthorized errors:
Verify your LIGHTDASH_TOKEN is correct and starts with ldt_
Check that the token hasn't expired
Ensure you have the necessary permissions in Lightdash
If you see connection errors:
Verify LIGHTDASH_URL is correct
For Lightdash Cloud: use https://app.lightdash.cloud
For self-hosted: use https://your-domain.com
If behind Cloudflare Access, ensure CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET are set
If behind Google Cloud IAP, ensure IAP_ENABLED=true is set, install with pip install lightdash-mcp[iap], and verify the service account has serviceAccountTokenCreator on itself
If a tool isn't showing up:
Check that the file is in the tools/ directory
Ensure the file has a TOOL_DEFINITION variable
Verify the file isn't in the exclusion list in tools/__init__.py
Restart the MCP server
Contributions are welcome! Please:
Fork the repository
Create a feature branch
Add your changes with appropriate tests
Submit a pull request
This project is licensed under the MIT License - see the LICENSE file for details.
For issues and questions:
Create a new saved chart in a space. Requires table name, metric query, and chart configuration.
⚠️ CRITICAL: Chart configuration structure must be precise or the chart will break!
═══════════════════════════════════════════════════════════════════ COMPLETE WORKING EXAMPLE - Line Chart with Count Distinct Metric: ═══════════════════════════════════════════════════════════════════
metricQuery: { "exploreName": "my_table", "dimensions": ["my_table_date_day"], "metrics": [], "filters": { "dimensions": { "id": "root", "and": [ { "id": "filter_1", "target": {"fieldId": "my_table_country"}, "operator": "equals", "values": ["US"] }, { "id": "filter_2", "target": {"fieldId": "my_table_date_day"}, "values": [30], "operator": "inThePast", "required": false, "settings": { "completed": false, "unitOfTime": "days" } } ] } }, "sorts": [{"fieldId": "my_table_date_day", "descending": true}], "limit": 500, "tableCalculations": [], "additionalMetrics": [ { "name": "dau", "label": "Daily Active Users", "description": "Count of unique users", "type": "count_distinct", "sql": "${TABLE}.user_id", "table": "my_table", "baseDimensionName": "user_id", "formatOptions": {"type": "default", "separator": "default"} } ] }
chartConfig: { "type": "cartesian", "config": { "layout": { "xField": "my_table_date_day", "yField": ["my_table_dau"], "flipAxes": false }, "eChartsConfig": { "xAxis": [{"name": "Date"}], "yAxis": [{"name": "DAU"}], "series": [ { "type": "line", "encode": { "xRef": {"field": "my_table_date_day"}, "yRef": {"field": "my_table_dau"} }, "yAxisIndex": 0 } ] } } }
pivotConfig (optional): { "columns": ["my_table_country"] }
═══════════════════════════════════════════════════════════════════ EXAMPLE WITH CUSTOM DIMENSIONS - Stacked/Segmented Charts: ═══════════════════════════════════════════════════════════════════
Use Case: Create grouped/segmented visualizations by categorizing data into meaningful buckets (e.g., Top N + "Other" pattern, status groupings, etc.)
metricQuery: { "exploreName": "your_table", "dimensions": ["your_table_date_day", "category_dimension"], "metrics": [], "filters": { "dimensions": { "id": "root", "and": [ { "id": "filter_1", "target": {"fieldId": "your_table_date_day"}, "values": [30], "operator": "inThePast", "required": false, "settings": {"completed": false, "unitOfTime": "days"} } ] } }, "sorts": [{"fieldId": "your_table_date_day", "descending": true}], "limit": 500, "additionalMetrics": [ { "name": "unique_count", "label": "Unique Count", "type": "count_distinct", "sql": "${TABLE}.identifier_column", "table": "your_table", "baseDimensionName": "identifier_column" } ], "customDimensions": [ { "id": "category_dimension", "name": "Category Dimension", "type": "sql", "table": "your_table", "sql": "CASE\n WHEN raw_field = 'value1' THEN 'Category A'\n WHEN raw_field = 'value2' THEN 'Category B'\n WHEN raw_field IN ('value3', 'value4') THEN 'Category C'\n ELSE 'Other'\n END", "dimensionType": "string" } ] }
chartConfig: { "type": "cartesian", "config": { "layout": { "xField": "your_table_date_day", "yField": ["your_table_unique_count"], "flipAxes": false }, "eChartsConfig": { "xAxis": [{"name": "Date"}], "yAxis": [{"name": "Count"}], "series": [ { "type": "bar", "stack": "your_table_unique_count", "encode": { "xRef": {"field": "your_table_date_day"}, "yRef": {"field": "your_table_unique_count"} }, "yAxisIndex": 0 } ] } } }
pivotConfig: { "columns": ["category_dimension"] }
Key Pattern: The custom dimension "category_dimension" is:
Defined in customDimensions with SQL CASE logic
Added to dimensions array for grouping
Used in pivotConfig.columns to create separate stacks/segments per category Result: One stacked segment per CASE branch, visualizing data by category over time
═══════════════════════════════════════════════════════════════════ KEY RULES (MUST FOLLOW): ═══════════════════════════════════════════════════════════════════
additionalMetrics naming:
Metrics are referenced as: "{table}_{metricName}"
Example: table="my_table", name="dau" → "my_table_dau"
series.encode MUST use objects (NOT strings): ✅ CORRECT: "xRef": {"field": "my_table_date_day"} ❌ WRONG: "xRef": "my_table_date_day"
eChartsConfig.series is required:
Must have at least one series object
Each series MUST have: type, encode.xRef, encode.yRef
Metric types for additionalMetrics:
"count_distinct": COUNT(DISTINCT field)
"count": COUNT(*)
"sum": SUM(field)
"avg": AVG(field)
"min": MIN(field)
"max": MAX(field)
Filter operators and structures:
Simple filters:
"equals": {"operator": "equals", "values": ["US"]}
"notEquals": {"operator": "notEquals", "values": ["US"]}
"contains": {"operator": "contains", "values": ["search_term"]}
"notNull": {"operator": "notNull"}
"isNull": {"operator": "isNull"}
Time-based filters (CRITICAL - note the structure): The "inThePast" operator requires specific structure: { "id": "filter_1", "target": {"fieldId": "table_date_field"}, "values": [30], # ← Number goes HERE in values array "operator": "inThePast", "required": false, "settings": { "completed": false, # ← Must be FALSE (not true) "unitOfTime": "days" # Options: "days", "weeks", "months", "years" } }
⚠️ Common mistakes to AVOID: ❌ WRONG: "settings": {"number": 30} → Number does NOT go in settings ❌ WRONG: "completed": true → Must be false ✅ CORRECT: "values": [30] + "completed": false
Pivot configuration:
Use pivotConfig to split series by dimension values
Example: {"columns": ["my_table_country"]} creates one line per country
This enables grouping/segmentation in charts
Custom Dimensions (customDimensions):
Create calculated dimensions using SQL expressions (CASE, CONCAT, etc.)
Custom dimensions can be used in dimensions array, pivots, and filters
Each custom dimension requires: id, name, type, table, sql, dimensionType
Structure: { "id": "custom_dim_id", # Unique identifier to reference in dimensions/pivots "name": "Custom Dimension Name", # Display name shown in UI "type": "sql", # Always "sql" for custom dimensions "table": "base_table", # Base table name (matches exploreName) "sql": "CASE WHEN ... THEN ... ELSE ... END", # SQL expression "dimensionType": "string" # Data type: "string", "number", "date", etc. }
Common Patterns:
a) Top N + "Other" grouping (reduce cardinality): { "id": "top_items_group", "sql": "CASE WHEN item_name = 'TopItem1' THEN 'TopItem1' WHEN item_name = 'TopItem2' THEN 'TopItem2' WHEN item_name IN ('TopItem3', 'TopItem4') THEN 'TopItem3/4' ELSE 'Other' END", "dimensionType": "string" }
b) Status/Category mapping: { "id": "status_group", "sql": "CASE WHEN status IN ('active', 'pending') THEN 'Active' WHEN status IN ('completed', 'archived') THEN 'Completed' ELSE 'Other' END", "dimensionType": "string" }
c) Numeric bucketing: { "id": "value_bucket", "sql": "CASE WHEN amount < 10 THEN 'Small' WHEN amount < 100 THEN 'Medium' ELSE 'Large' END", "dimensionType": "string" }
Usage in metricQuery:
Add to customDimensions array: "customDimensions": [...]
Reference by id in dimensions: "dimensions": ["table_date", "custom_dim_id"]
Use in pivots: "pivotConfig": {"columns": ["custom_dim_id"]}
Filter on custom dimensions just like regular dimensions
Benefits:
Reduce high-cardinality dimensions to manageable segments
Apply business logic without modifying base tables
Create "Top N + Other" patterns for cleaner visualizations
Categorize raw values into meaningful groups
With Pivots - Creating Segmented Charts: When a custom dimension is used in BOTH dimensions array AND pivotConfig.columns, Lightdash creates one separate series/segment per unique value from the CASE statement. Example: 5 CASE branches = 5 stacked segments in the chart.
═══════════════════════════════════════════════════════════════════ CHART TYPES: ═══════════════════════════════════════════════════════════════════
Line Chart: series[].type = "line" Bar Chart: series[].type = "bar" Area Chart: series[].type = "line" + series[].areaStyle = {} Stacked Area: series[].type = "line" + series[].areaStyle = {} + series[].stack = "stack_name"
═══════════════════════════════════════════════════════════════════ VALIDATION: ═══════════════════════════════════════════════════════════════════
The server will automatically:
Validate chart config structure (xRef/yRef objects)
Validate field references match metricQuery
Auto-generate tableConfig.columnOrder
Add additionalMetrics to metrics array for proper display
If validation fails, you'll get a detailed error message.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the chart | |
| table_name | Yes | Name of the table/explore to query (use get-explore-schema to find available tables) | |
| space_uuid | Yes | UUID of the space to save the chart in (use list-spaces to find UUIDs) | |
| metric_query | Yes | JSON string of the metric query configuration (see description for complete example) | |
| chart_config | Yes | JSON string of the chart visualization configuration (see description for complete example with proper eChartsConfig structure) | |
| pivot_config | No | Optional: JSON string for pivot configuration to group data by dimension. Example: {"columns": ["table_dimension"]} creates separate series for each dimension value | |
| description | No | Optional description of the chart |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully bears the burden. It details that the chart is saved in a space, requires precise configuration, and warns that a wrong structure will break the chart. It also mentions server-side validation and auto-generation, providing a complete behavioral picture.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very long with multiple sections and verbose examples. While well-organized for complexity, it sacrifices conciseness. Every sentence is informative, but the overall length could be reduced without losing essential guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (7 parameters, 5 required, no output schema), the description is thoroughly complete. It covers metric queries, chart configs, pivot configs, custom dimensions, chart types, and validation—addressing all potential user needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the input schema already has 100% coverage, the description adds immense value with complete working examples, naming conventions, filter structures, custom dimension patterns, and validation rules. This goes far beyond the schema's basic parameter descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new saved chart in a space' and lists required components (table name, metric query, chart configuration). It distinguishes the tool from siblings like update-chart and delete-chart by focusing on creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive examples and key rules, implicitly guiding when to use this tool (creating a chart). It lacks explicit comparison to alternatives like run-chart-query but covers use cases and critical warnings, which is sufficient for a creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new dashboard in the Lightdash project.
You can create an empty dashboard (just name and description) or a fully configured dashboard with tiles and tabs.
Tile Types:
saved_chart: Display a saved chart (requires savedChartUuid in properties)
markdown: Text/markdown content (requires title and content in properties)
loom: Embedded Loom video (requires url in properties)
Tile Position Properties (required for each tile):
x: Column position (0-indexed, grid is 12 columns wide)
y: Row position (0-indexed)
h: Height in grid units
w: Width in grid units (max 12)
When to use:
To create a new empty dashboard that you'll populate later
To create a fully configured dashboard from a template or copy
Use duplicate-dashboard if you want to copy an existing dashboard
Best practice: Start with an empty dashboard, then use create-dashboard-tile to add content.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the dashboard (must be unique within the project) | |
| description | No | Optional: Description explaining the purpose of this dashboard | |
| tiles | No | Optional: JSON string array of tiles to add to the dashboard. Each tile needs type, properties with x/y/h/w positioning. Example: [{"uuid": "uuid1", "type": "markdown", "properties": {"title": "Welcome", "content": "# Hello"}, "x": 0, "y": 0, "h": 4, "w": 12}] | |
| tabs | No | Optional: JSON string array of tabs for organizing tiles. Example: [{"uuid": "tab-uuid", "name": "Overview", "order": 0}] |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must cover behavioral traits. It explains tile types and positioning but lacks details on idempotency, return value, error handling for duplicate names, or required permissions. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections, bullet points, and separate usage guidelines. While slightly lengthy, every sentence adds meaningful information. No unnecessary redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, yet description does not specify return value or confirmation of creation. However, for a creation tool with 4 parameters and clear schema, the description covers creation process and use cases sufficiently. Minor gap on output.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. The description adds extra value by detailing tile types, properties structure, and positioning, which enriches understanding beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new dashboard, and distinguishes from siblings like duplicate-dashboard and create-dashboard-tile. It specifies the ability to create empty or fully configured dashboards.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' section lists three scenarios and references alternative tool (duplicate-dashboard). Best practice recommendation to start empty and use create-dashboard-tile provides further guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new tile and add it to an existing dashboard.
Required for all tiles:
Position and size: x, y, h, w (in the properties JSON)
Tile type: One of 'saved_chart', 'markdown', 'loom'
Tile-specific requirements:
saved_chart tiles:
savedChartUuid: UUID of the chart to display (use list-charts to find)
Optional: title to override the chart's name
markdown tiles:
title: Display title
content: Markdown content to display
loom tiles:
url: Loom video URL
Optional: title
CRITICAL - Grid system:
Dashboard is 36 columns wide (not 12!)
x ranges from 0-35 (column position)
y is row position (grows downward)
w is width in columns (1-36)
h is height in grid units
For 2 tiles per row: use w: 18 each
For 3 tiles per row: use w: 12 each
For full width: use w: 36
When to use:
To add charts to a dashboard
To add markdown documentation/headers
To embed Loom videos for context
Best practice: Use get-dashboard-tiles first to see existing layout and find an empty position.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_type | Yes | Type of tile: 'saved_chart' (for charts), 'markdown' (for text), or 'loom' (for videos) | |
| properties | Yes | JSON object string with tile properties. MUST include x, y, h, w for positioning. Example for chart: {"x": 0, "y": 0, "h": 6, "w": 18, "savedChartUuid": "uuid-here"} | |
| tab_uuid | No | Optional: UUID of the tab to add the tile to. Leave empty to use the first tab (or no tab if dashboard has no tabs). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description fully covers behavior: details the grid system (36 columns), tile-specific required fields, and positioning. It does not mention side effects like overwriting, but creation is inherently non-destructive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and examples, but slightly verbose. Every sentence adds value, and critical information (grid system) is highlighted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of multiple tile types and no output schema, the description thoroughly explains all necessary details for correct invocation, including parameter usage and best practices.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds significant value beyond the schema, detailing tile-specific properties for each type (saved_chart, markdown, loom) and the grid system. Schema coverage is 100%, but the description provides execution-critical examples and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a new tile and adds it to an existing dashboard, with explicit tile types and their requirements. It distinguishes from siblings like 'create-chart' and 'delete-dashboard-tile' by focusing on tile creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists three specific use cases, and the best practice to first retrieve existing tiles provides context. However, it does not explicitly exclude alternatives or compare to siblings like 'update-dashboard-tile'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new space (folder) to organize charts and dashboards.
Spaces help organize content by:
Team (e.g., "Marketing Analytics", "Finance")
Product area (e.g., "User Growth", "Revenue")
Development stage (e.g., "Production Dashboards", "Development")
When to use:
Before creating charts that belong to a new category
To organize existing content into logical groups
To set up restricted areas for sensitive data (use is_private=true)
Best practices:
Use descriptive names that indicate content purpose
Create private spaces for sensitive or work-in-progress content
Get the space UUID from the response to use when creating charts
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name of the space. Should be descriptive and indicate the type of content it will contain. | |
| is_private | No | Whether the space is private (restricted access). Default: false (public space visible to all users) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses creation behavior, notes the response contains the space UUID, and mentions private vs public spaces. However, it does not specify error conditions like duplicate names or permission requirements, which would improve transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear opening, bullet points for use cases and best practices, and no redundant information. Every sentence adds value, and the key action is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (2 params) and no output schema, the description covers purpose, usage context, parameter guidance, and what to expect from the response (space UUID). It is complete for an agent to correctly select and use this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters ('name', 'is_private') have descriptions in the schema. The description adds context with examples of space categories and best practices for naming and privacy, enhancing understanding beyond the schema fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool creates a 'space (folder)' for organizing charts and dashboards. The verb 'create' combined with the resource 'space' is specific. It distinguishes from siblings like 'create-chart' and 'create-dashboard' by focusing on organizational structure.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit 'When to use' section with three bullet points covering before creating charts, organizing content, and setting up restricted areas. 'Best practices' offer further guidance. This clearly tells the agent when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a saved chart from the project.
Warning: This is a destructive operation and cannot be undone.
When to use:
To remove outdated or incorrect charts
To clean up test/development charts
Before recreating a chart with the same name (delete old, create new)
Important notes:
Charts still referenced on dashboards will show as broken/missing after deletion
Consider checking which dashboards use this chart before deleting (use get-dashboard-tiles)
For modifying existing charts, use update-chart instead of delete + recreate
Accepts: Either chart UUID or chart name (will search for exact match)
| Name | Required | Description | Default |
|---|---|---|---|
| chart_identifier | Yes | Chart name (exact match) or UUID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Warns that operation is destructive and irreversible, and that dashboard references will break. Suggests checking dependencies beforehand. No annotations exist, so description carries full burden and handles it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate sections for warning, usage, notes, and accepted input. Front-loaded with purpose. Every sentence is informative, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers all relevant aspects: destructive nature, dependencies, alternatives, input types, and consequences. No output schema needed for delete; description is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with parameter description. Description adds clarification that name search is exact match, but largely reinforces schema. Minor added value above baseline.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Delete a saved chart from the project' with specific verb and resource. Distinguishes from sibling tools like update-chart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use scenarios (outdated charts, test cleanup, recreation) and when not (modifications, recommends update-chart). Also advises checking dashboard dependencies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a tile from a dashboard.
This permanently removes a tile from the dashboard. The operation cannot be undone.
When to use:
To remove outdated or unwanted tiles from a dashboard
To clean up dashboards during reorganization
To remove tiles before replacing them with updated versions
Important notes:
This is a destructive operation - the tile cannot be recovered after deletion
If the tile displays a saved chart, the chart itself is NOT deleted (only the tile reference)
Dashboard-only charts (charts that exist only in the tile) will be permanently lost
You should save the dashboard after deletion (this is done automatically)
Search behavior: Matches tile titles case-insensitively with partial matching.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_identifier | Yes | Title of the tile or partial match to identify which tile to delete (e.g., 'active users' will match 'Daily Active Users Chart') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses the destructive nature ('permanently removes', 'cannot be undone'), effects on saved charts versus dashboard-only charts, and automatic saving after deletion. This provides comprehensive behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear headings, bullet points, and concise sentences. Each section serves a distinct purpose: purpose, usage, important notes, and search behavior. No extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all critical aspects for a deletion tool: irreversibility, effect on charts, automatic saving, and search behavior. However, it does not address error scenarios (e.g., tile not found) or specify the output of the operation. Given no output schema, slightly more detail on expected results could enhance completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (100% coverage). The description adds value by explaining partial matching behavior for dashboard_name and tile_identifier, including an example for tile_identifier. This enriches the schema information without being redundant.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's purpose: permanently deleting a tile from a dashboard. It uses specific verbs ('Delete') and resource ('tile'), and distinguishes it from sibling tools like rename-dashboard-tile or update-dashboard-tile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit use cases (removing outdated tiles, cleanup, replacing tiles) and implies when not to use (e.g., when the chart itself should be preserved). However, it lacks explicit alternative tool names for related operations, such as delete-chart for deleting the underlying chart.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a space (folder).
Important constraints:
Cannot delete spaces that contain charts or dashboards
Must move or delete all content from the space first
This is a permanent operation
When to use:
To remove empty, unused spaces
To clean up organizational structure
After moving all content to other spaces
Steps to delete a space with content:
List charts and dashboards in the space
Move them to other spaces or delete them
Delete the now-empty space
Accepts: Either space UUID or space name (will search for exact match)
| Name | Required | Description | Default |
|---|---|---|---|
| space_identifier | Yes | Space name (exact match) or UUID to delete. Space must be empty (no charts or dashboards). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully discloses constraints (cannot delete if contains charts/dashboards, permanent operation), input types (UUID or name), and prerequisite steps. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections and bullet points. Every sentence adds value, though slightly verbose. Could be more concise but still efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 1 parameter, no output schema, and no annotations, the description covers constraints, usage, steps, and input details comprehensively. No gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 100% coverage for the single parameter, and the description adds only minor clarification about exact match for name. Baseline is 3 due to high schema coverage; description adds marginal extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Delete a space (folder)' with a specific verb and resource. It distinguishes from sibling tools like create-space and list-spaces by focusing on the deletion action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (remove empty/unused spaces, clean up, after moving content) and provides steps to delete a space with content. Offers clear guidance on prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a complete copy of an existing dashboard with a new name.
This copies everything from the source dashboard:
All tiles with their positions and configurations
All tabs (if the dashboard has tabs)
Dashboard-level filters
Layout and styling
What gets regenerated:
Dashboard UUID (new unique ID)
Tile UUIDs (new IDs for each tile)
Tab UUIDs (new IDs for each tab)
What stays the same:
Chart references (tiles still point to the same charts)
Content and configuration
Layout and positioning
When to use:
To create dashboard variants for different teams/regions
To create a test version before modifying production dashboards
To use an existing dashboard as a template
To create regional/customer-specific versions
Best practice: Use descriptive names to distinguish the copy from the original.
| Name | Required | Description | Default |
|---|---|---|---|
| source_dashboard_name | Yes | Name of the dashboard to copy (supports partial matching) | |
| new_dashboard_name | Yes | Name for the new dashboard copy. Must be unique in the project. | |
| new_description | No | Optional: Description for the new dashboard. If omitted, copies the source dashboard's description. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It explicitly lists what gets copied (tiles, tabs, filters, layout), what gets regenerated (UUIDs), and what stays the same (chart references). This is comprehensive for a duplicate operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections and bullet points. Every sentence adds value. The core purpose is front-loaded immediately. No wasted words for a tool of this complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately explains the behavior (complete copy, UUID regeneration, chart references preserved). It includes all necessary context for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds value by explaining 'partial matching' for source_dashboard_name and uniqueness requirement for new_dashboard_name, which go beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Create a complete copy of' and identifies the resource as an 'existing dashboard with a new name'. It clearly distinguishes from 'create-dashboard' by emphasizing copying rather than creation from scratch.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists four concrete scenarios (e.g., creating variants, test versions). It implicitly suggests when not to use (e.g., when creating from scratch, use create-dashboard). Could be improved by explicitly naming alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific saved chart.
Returns complete chart configuration including:
Chart type and visualization settings (eChartsConfig)
Metric query configuration (dimensions, metrics, filters, sorts)
Table configuration (column order, conditional formatting)
Metadata (name, description, space, timestamps)
When to use:
Before modifying or duplicating a chart
To understand how a chart is configured
To extract query logic for reuse
To debug chart issues
Accepts: Either chart UUID or chart name (will search for exact match)
| Name | Required | Description | Default |
|---|---|---|---|
| chart_identifier | Yes | Chart name (exact match) or UUID to look up |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries burden. States return categories and that it accepts UUID or name with exact match. Lacks explicit statement that it is read-only or details on error handling/performance, but adequately describes the operation's scope.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, well-structured with bullet points and headings. Every sentence adds value, no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read operation with no output schema, the description covers key return categories (chart config, metrics, table config, metadata). Could add more detail on response structure, but sufficient for agent to understand what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter clearly described. Description adds 'will search for exact match' nuance, but schema already explains the parameter. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get detailed information about a specific saved chart' and lists specific return categories, distinguishing it from sibling tools like get-dashboard-tile-chart-config.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly listed 'When to use' bullet points (before modifying, understanding config, extracting query logic, debugging). No explicit when-not-to-use or alternative tools mentioned, but the guidance is clear and actionable.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get custom metrics defined in the project.
Custom metrics are user-defined metrics created in the Lightdash UI that aren't part of the dbt model definitions. These are stored separately and can be used in charts and dashboards.
Returns:
Custom metric definitions
SQL expressions used to calculate them
Associated tables/explores
Labels and descriptions
When to use:
To discover custom business metrics created by analysts
To understand what custom calculations are available
Before using a custom metric in a chart or query
Note: These are different from metrics defined in your dbt models.
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No | Optional: UUID of the project. If not provided, uses current project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully discloses that these are user-defined metrics stored separately from dbt models, and that it returns definitions, SQL expressions, associated tables, and labels. It does not mention any side effects or destructive actions, which is appropriate for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with paragraphs and bullet points, making it easy to scan. It is clear and informative without being overly verbose, though it could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite no output schema, the description lists return fields and clearly explains the tool's function. For a simple get operation with one optional parameter, it provides sufficient context. Possible minor improvements: mention if pagination is supported.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for the single optional parameter, so the description adds no new information beyond 'if not provided, uses current project' which is already in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool retrieves custom metrics defined in the project, distinguishes them from dbt model metrics, and lists return fields. The verb 'Get' clearly identifies the action, and the resource 'custom metrics' is well-defined.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section with three specific scenarios: discovering custom business metrics, understanding custom calculations, and before using a metric in a chart/query. It also notes the difference from dbt model metrics, providing clear guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete dashboard configuration including full tile definitions.
Returns the raw dashboard configuration as code, including:
All tile definitions with complete properties
Tab configuration
Filter configuration
Layout information
Chart references
When to use:
To export a dashboard for version control
To understand the complete structure of a complex dashboard
Before programmatically duplicating a dashboard
To backup dashboard configurations
To debug dashboard issues
Use cases:
Backup: Save dashboard configs before making changes
Version control: Track dashboard changes over time
Migration: Move dashboards between projects/environments
Templates: Create reusable dashboard templates
Alternative: Use duplicate-dashboard for a simpler way to copy dashboards.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but the description thoroughly explains the return value (config details) and implies a read-only operation, with no contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and sections, each sentence adds value without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description sufficiently details the return content (tiles, tabs, filters, layout, chart references) and use cases, making it complete for a read tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the parameter description already includes 'supports partial matching'. The tool description adds no additional semantic value beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it returns the complete dashboard configuration with full tile definitions, and distinguishes from the sibling tool 'duplicate-dashboard' by noting it as an alternative for simpler copying.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' and 'Use cases' sections, including a specific alternative tool, provide clear guidance on when to invoke this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete chart configuration for a dashboard tile, including dashboard-only charts.
Dashboard-only charts store their full configuration (metric query, chart config, visualization settings) directly in the dashboard tile structure. This tool extracts that complete configuration.
Returns:
Complete chart configuration including:
metricQuery: The query configuration (dimensions, metrics, filters, sorts)
chartConfig: Visualization configuration (chart type, axes, series)
tableConfig: Table column configuration
pivotConfig: Pivot configuration if applicable
For saved charts: retrieves the chart via the savedChartUuid reference
For dashboard-only charts: extracts from tile's belongsToChart property
When to use:
To get full details of a a chart visible on a dashboard
To understand the configuration of dashboard-only charts
To export or duplicate dashboard-only chart configurations
Before modifying a dashboard tile's chart
Parameters:
dashboard_name: Name of the dashboard (supports partial matching)
tile_identifier: Title of the tile or partial match
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_identifier | Yes | Title of the tile or partial match to identify which tile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries the burden. It discloses the two behaviors (saved vs dashboard-only) and the full list of returned configurations. It mentions partial matching support. No contradictions or hidden side effects described.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with clear sections (introduction, returns, usage, parameters). Front-loaded with main purpose. Contains one minor typo ('a a chart' in second bullet of usage) but otherwise every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only two parameters, no output schema, and the tool's retrieval nature, the description is comprehensive. It explains the difference between chart types and lists all config components. Could mention error handling (e.g., tile not found) but overall sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. Description adds minimal new meaning beyond schema: both parameters already have descriptions mentioning partial matching. The context of use is provided but doesn't significantly enhance the schema information.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves the complete chart configuration for a dashboard tile, distinguishing between saved charts and dashboard-only charts. It specifies the exact components returned (metricQuery, chartConfig, etc.) and separates from sibling tools like get-dashboard-tiles or get-chart-details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
A 'When to use' section provides four explicit contexts (getting full details, understanding dashboard-only charts, exporting, before modifying). It implicitly differentiates from get-chart-details for saved charts, but could be more explicit about alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all tiles from a specific dashboard.
Returns a list of all tiles on the dashboard with their:
UUID (unique identifier)
Type (saved_chart, markdown, loom, etc.)
Title or chart name
savedChartUuid (for chart tiles)
Position and size (x, y, h, w)
OPTIONAL: Full chart configuration if include_full_config=true
When to use:
To see what content is on a dashboard before modifying it
To find a tile's UUID for update or delete operations
To understand the layout of a dashboard
To find which charts are used on a dashboard
To get full configuration of dashboard-only charts
Search behavior: Matches dashboard names case-insensitively with partial matching.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching, e.g., 'Scale' will match 'Scale Dashboard') | |
| include_full_config | No | Optional: If true, includes complete chart configuration for each tile (including dashboard-only charts). Default: false |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It discloses the optional include_full_config behavior and return fields, but does not mention side-effect-free nature, permissions, or rate limits. Acceptable for a read tool, but could be more explicit about safety.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, starting with a clear summary, followed by a bulleted return field list, and a 'When to use' section. Every sentence adds value with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Without an output schema, the description adequately explains return values. It covers all key fields and the optional configuration. Minor missing details like error cases or pagination, but sufficient for typical use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, baseline 3. The description adds contextual value by explaining that dashboard_name supports partial case-insensitive matching and that include_full_config provides full chart configuration for each tile, extending beyond the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get all tiles from a specific dashboard' and enumerates the return fields, distinguishing this read operation from sibling tools like create-dashboard-tile, update-dashboard-tile, and delete-dashboard-tile.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists five specific use cases, such as finding a tile's UUID for update/delete, understanding layout, or getting full configuration. It lacks explicit when-not-to-use or alternatives, but the provided guidance is comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the complete schema for an explore/table including all available dimensions, metrics, and joins.
This is essential before creating charts to understand what fields exist and their types.
Returns:
Base table information: Name, label, description
All dimensions by table: Field IDs, types, labels, descriptions
All metrics by table: Field IDs, types, SQL, labels, descriptions
Joins: How tables are connected, join types, join conditions
Summary statistics: Counts of tables, dimensions, metrics
Field information includes:
fieldId: Use this exact value in chart queries (format: table_fieldname)
type: Field data type (string, number, date, timestamp, etc.)
label: Human-readable name
description: What the field represents
hidden: Whether field is hidden by default
sql: For metrics, the SQL expression used
When to use:
Before creating any chart - to find correct field IDs
To understand available data and metrics
To discover join relationships between tables
To find field types for proper formatting
To explore what analysis is possible with a data model
Best practices:
Start with get-catalog or get-metrics-catalog to find relevant explores
Use get-explore-schema on specific explores to get detailed field information
Copy exact fieldId values when building chart queries
Check field descriptions to ensure you're using the right data
Hidden fields: By default, hidden fields are excluded. Set include_hidden=true to see all fields including internal/technical ones.
| Name | Required | Description | Default |
|---|---|---|---|
| table_name | Yes | Name of the table/explore to introspect. This is the exploreName from your dbt models (e.g., 'snowplow__events_processed', 'wallet_users', 'orders'). Use get-catalog to discover available explore names. | |
| include_hidden | No | Optional: Include hidden fields in the response (default: false). Hidden fields are typically internal or technical fields not meant for general use. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses return structure (base table info, dimensions, metrics, joins, summary stats), field details, and hidden fields behavior. It does not mention idempotency or side effects, but for a read-only tool this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections, bullet points, and clear formatting. It is detailed but not verbose; every sentence adds value. Information is front-loaded with the core purpose, then detailed sections.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite having no output schema, the description provides extensive detail on return content (field IDs, types, labels, SQL, descriptions, joins). For a schema retrieval tool, this covers all necessary aspects and compensates fully for the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (both parameters documented). The description adds value beyond schema: for table_name it gives concrete examples and references get-catalog; for include_hidden it clarifies what hidden fields are. This helps the agent use parameters correctly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get the complete schema for an explore/table including all available dimensions, metrics, and joins.' It uses a specific verb and resource, and distinguishes from sibling tools like get-catalog (which lists explores) and run-chart-query (which uses the schema).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section listing explicit scenarios (e.g., before creating any chart) and 'Best practices' with sequential steps referencing sibling tools like get-catalog. It provides clear context and exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed information about a specific project.
Returns comprehensive project details including:
Project configuration and settings
Warehouse connection information
dbt integration details
Project metadata
When to use: When you need detailed configuration information about a specific project, such as its warehouse connection, dbt settings, or other metadata.
Parameters:
project_uuid: Optional. If not provided, uses the current/default project.
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No | Optional: UUID of the project. If not provided, uses current project from LIGHTDASH_PROJECT_UUID env var or first available project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. The verb 'Get' implies a read-only operation, and the description lists the type of information returned, making the behavior clear. However, it does not mention any potential side effects, response format, or error conditions, which would be beneficial for full transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear main statement, bullet points for returned details, a separate usage section, and a parameter section. It is concise and front-loaded, with no unnecessary sentences. Minor improvement could be to integrate the parameter description more naturally.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given there is no output schema and no annotations, the description provides a high-level overview of what is returned (configuration, warehouse connection, dbt details, metadata). However, it lacks specifics on the exact fields or structure, which might leave an agent needing more detail to decide if the tool meets its needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage with a detailed description of the project_uuid parameter (mentioning env var and fallback). The tool description's parameter info says 'Optional. If not provided, uses the current/default project,' which is less precise and does not add meaning beyond the schema. It actually omits details, so it provides no added value and may be slightly misleading.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states the tool retrieves detailed information about a specific project, using the verb 'Get' and the resource 'project'. It distinguishes itself from sibling tools like list-projects by emphasizing 'detailed configuration information' and listing specific details such as warehouse connection and dbt settings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to use' section that clearly explains the scenario: when you need detailed configuration information about a specific project. It provides explicit examples of the kind of details returned. However, it does not explicitly state when not to use it or directly name alternative tools like list-projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all saved charts in the Lightdash project.
Returns chart information including:
Chart UUID and name
Space (folder) the chart belongs to
Description
Last updated timestamp
When to use:
To discover available charts in the project
To find a chart UUID for adding to dashboards or querying
To get an overview of what visualizations exist
To filter charts by name before getting details
Optional search_term: Filters the list to only charts matching the search term in their name.
| Name | Required | Description | Default |
|---|---|---|---|
| search_term | No | Optional: Filter charts by name (case-insensitive partial match). Example: 'revenue' will match 'Monthly Revenue Chart' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It clearly states the tool is read-only and lists the information returned (UUID, name, space, description, last updated). No hidden side effects or requirements are omitted.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a clear first sentence, a bullet list of return information, and a dedicated 'When to use' section. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter. Despite no output schema, the description adequately lists the return fields, making it complete for an agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 100% schema coverage, baseline is 3. The description adds value by providing an explicit usage example for the search_term parameter, enhancing understanding beyond the schema description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The purpose is crystal clear: 'List all saved charts in the Lightdash project.' It specifies the verb (list) and resource (charts) and distinguishes itself from sibling tools like 'search-charts' which likely has different functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' bullet points covering common use cases. However, it does not explicitly state when not to use or compare to similar tools like 'search-charts', though the usage guidance is still helpful.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all dashboards in the Lightdash project.
Returns dashboard metadata including:
Dashboard UUID and name
Description
Space (folder) the dashboard belongs to
View and update timestamps
When to use:
To discover available dashboards
To find a dashboard UUID for other operations
To get an overview of dashboard organization
Next steps: Use get-dashboard-tiles to see what's on a dashboard, or get-dashboard-code to get the complete configuration.
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No | Optional: UUID of the project. If not provided, uses current project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description describes return values (metadata fields) and implies a safe read operation. With no annotations, it carries the full burden but is sufficiently transparent for a list tool, though it could mention permission scoping or pagination.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear single-sentence purpose, a bullet list of return data, and separate 'When to use' and 'Next steps' sections. No redundant or unnecessary information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input (one optional param) and no output schema or nested objects, the description is fairly complete. It covers purpose, return data, and usage context, though it lacks details on ordering or pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage on the single optional parameter project_uuid. The description does not add extra meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all dashboards' with a specific resource and action, and the 'When to use' section distinguishes it from sibling tools like list-charts and list-spaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' section provides three clear scenarios for using the tool, and 'Next steps' suggests specific follow-up tools (get-dashboard-tiles, get-dashboard-code), giving clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available explores/tables in the project catalog.
Returns a catalog of all tables/explores organized by project and dataset:
Explore/table names
Table descriptions
SQL table references
When to use:
To discover what tables/explores are available in the project
To browse the data catalog and find relevant tables by description
Before using get-explore-schema to get detailed field information
Best practice: Use this for initial discovery to find table names, then use get-explore-schema for detailed dimensions, metrics, and joins.
Note: This can return large amounts of data for projects with many explores.
| Name | Required | Description | Default |
|---|---|---|---|
| project_uuid | No | Optional: UUID of the project. If not provided, uses current project. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It notes potential for large data return, which is a key behavioral trait. Describes it as a catalog listing, implying read-only, but doesn't explicitly confirm no side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and clear headings. Every sentence adds value. Front-loaded with purpose. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, when to use, and a behavioral note. Given one optional parameter and no output schema, the description is sufficient. Could mention authentication or error cases, but not necessary for core understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one optional parameter. Description restates the schema description ('Optional: UUID of the project. If not provided, uses current project.') without adding new semantic value. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all available explores/tables in the project catalog' and enumerates returned content (names, descriptions, SQL references). It distinguishes from sibling tools like get-explore-schema by indicating that list-explores is for initial discovery.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use: for discovery, browsing catalog, before using get-explore-schema. Includes best practice. Does not explicitly state when not to use, but context is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all projects in your Lightdash organization.
Returns project information including:
Project UUID (required for other API calls)
Project name and type
Database connection details (warehouse type)
Creation and update timestamps
When to use: Start here to discover available projects or to find the UUID of a project you want to work with. If LIGHTDASH_PROJECT_UUID environment variable is set, most other tools will use that project automatically.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explicitly state that this tool is read-only or safe to call repeatedly, nor does it mention any authentication or rate-limit considerations. The functional output is described, but behavioral traits are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with a clear sentence, bullet points for returned fields, and a separate usage guidance paragraph. It is front-loaded and each part serves a purpose, though it could be slightly more terse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and no output schema, the description adequately covers its purpose, returned information, and usage context (UUID requirement for other calls). It provides enough detail for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has no parameters, and schema coverage is 100%, so the description does not need to explain parameter details. The baseline score of 4 is appropriate since the description adds no parameter information but there is no need for it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists all projects in the Lightdash organization and specifies the returned fields (UUID, name, type, database connection details, timestamps). It distinguishes itself from sibling tools, none of which perform a similar project listing function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly advises starting here to discover projects or find UUIDs, and mentions the LIGHTDASH_PROJECT_UUID environment variable as an alternative for other tools. No explicit when-not or alternatives are needed since no other tool lists projects.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all spaces (folders) in the Lightdash project.
Spaces are organizational folders that contain charts and dashboards.
Returns for each space:
UUID and name
Whether it's private (restricted access)
Count of charts in the space
Count of dashboards in the space
When to use:
To discover organizational structure of content
To find space UUIDs for creating charts
To get an overview of content organization
Before creating new spaces to avoid duplicates
Space types:
Public spaces: Visible to all project users
Private spaces: Restricted to specific users/groups
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, but description fully explains the read-only behavior and the returned fields (UUID, name, private flag, counts) and space types. Omits pagination or limits, but acceptable for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with main purpose, uses bullet points and clear sections, no wasted words. Every sentence adds value, and structure aids quick scanning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description fully covers purpose, usage, return values, and space types. Sufficient for an AI agent to decide when and how to use the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist; schema coverage is 100% (vacuously). Description adds value by explaining the tool's behavior and return values beyond the empty schema, meeting the baseline of 4 for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List all spaces (folders) in the Lightdash project' with a specific verb and resource, and distinguishes itself from sibling tools like create-space and delete-space by focusing on listing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use' bullet points (e.g., discover structure, find UUIDs) and describes space types, giving clear context for usage. Lacks explicit alternatives or when-not-to-use, but is well-implied by sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Rename a tile on a dashboard by updating its title property.
This is a convenience tool for the common operation of changing a tile's display name.
When to use:
To change the title of a markdown tile
To override the display name of a chart tile
Quick title updates without modifying other properties
For more complex updates: Use update-dashboard-tile to change multiple properties at once.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_identifier | Yes | Current title of the tile or partial match (e.g., 'active users' will match 'Daily Active Users Chart') | |
| new_title | Yes | New title for the tile |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It correctly identifies the operation as renaming by updating the title property. While it lacks details on side effects or permissions, the operation is simple and the description is straightforward. Could be slightly improved by noting immediate effect or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Very concise, using only necessary sentences. Front-loaded with the main purpose. Uses section headers for guidelines. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Missing information about return values or success indicators (no output schema). Does not mention error cases or prerequisites (e.g., tile must exist). But for a simple rename, it covers the essential context of what the tool does and when to use it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has 100% coverage with clear parameter descriptions. The description adds no additional semantic information beyond what the schema provides, but the schema is already sufficient. Baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (rename a tile) and resource (dashboard tile) with specific verb+resource. It distinguishes itself from the sibling 'update-dashboard-tile' by noting it is a convenience tool for a single property update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Description includes explicit when-to-use scenarios (markdown tile, chart tile display name, quick updates) and explicitly mentions when not to use (complex updates: use update-dashboard-tile). Provides clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a chart query and return the data results in CSV format.
Runs the chart's configured query against the data warehouse and returns the results as CSV.
Returns:
CSV-formatted string with headers and data rows
Metadata comment line with row count (format: # Metadata: {"row_count":N})
When to use:
To get actual data from a chart for analysis
To verify a chart is returning expected results
To export chart data programmatically
To preview data before creating a dashboard tile
Performance notes:
Large result sets may take time to execute
Use the limit parameter to restrict rows returned
Query execution happens in real-time against your warehouse
Optional limit parameter: Restricts the number of rows returned (useful for large datasets)
| Name | Required | Description | Default |
|---|---|---|---|
| chart_uuid | Yes | UUID of the chart to execute | |
| limit | No | Optional: Limit number of rows returned. Useful for large datasets. Example: 100 will return max 100 rows |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses return format (CSV with metadata), real-time execution, performance notes, and optional limit. Does not explicitly state read-only, but implied by 'execute a chart query'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is well-organized with sections, front-loaded with core purpose. Every sentence provides value, no fluff. Approximately 150 words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters, no output schema, and moderate complexity, description covers purpose, usage, return format, and performance. Missing example or error handling, but adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds marginal value. It reiterates limit's purpose and provides example, but chart_uuid description repeats schema. Baseline 3 appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it 'executes a chart query and returns data in CSV format.' It uses specific verb+resource, and distinguishes from siblings like run-dashboard-tiles and run-raw-query.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists four appropriate scenarios (getting data, verifying chart, exporting, previewing). It lacks explicit exclusions or alternatives, but the usage context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run one or multiple dashboard tiles (or all tiles) concurrently.
This tool fetches the dashboard configuration once and then executes the selected tiles in parallel.
When to use:
To download the entire dashboard data.
To get data from multiple specific tiles at once (or from single tile).
Returns:
A dictionary where keys are tile UUIDs and values contain:
title: Tile title
status: "success" or "error"
csv_data: CSV-formatted string with headers, data rows, and metadata (for successful tiles)
error: Error message (for failed tiles)
Each CSV data includes a metadata comment line with row count and field information
If a tile fails to execute, the value will contain an error message.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_uuids | No | Optional: List of tile UUIDs to execute. If omitted or empty, ALL chart tiles on the dashboard will be executed. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses that the tool fetches dashboard configuration once and executes tiles in parallel. It also describes the return format including error handling for failed tiles. This provides sufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise with clear sections for 'When to use' and 'Returns'. It is front-loaded with the main action. There is no redundant information, and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description adequately describes the return values: a dictionary with keys for tile UUIDs, containing title, status, csv_data (with metadata), and error. It covers input parameters and behavior (parallel execution, fetching config once). It is complete for an AI agent to understand the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds valuable context: explaining that if tile_uuids is omitted or empty, all chart tiles are executed. It also details the return structure (tile UUIDs as keys, status, csv_data, error). This goes beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it runs one or multiple dashboard tiles concurrently. It distinguishes from sibling tools like run-chart-query by focusing on dashboard tiles. The verb 'run' and resource 'dashboard tiles' are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a 'When to use' section that lists appropriate scenarios: downloading entire dashboard data or getting data from multiple specific tiles. It does not explicitly state when not to use, but the context is clear enough for an AI to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a raw metric query against a Lightdash explore.
This tool allows you to run arbitrary queries by specifying dimensions, metrics, filters, and sorts directly. It is useful for:
Running ad-hoc analysis without creating a saved chart
Executing queries for dashboard-only charts (which don't have a saved chart UUID)
Debugging data issues by running simplified queries
Input:
explore_name: The name of the explore (table) to query.
metric_query: The query definition (dimensions, metrics, filters, etc.).
limit: Optional row limit.
═══════════════════════════════════════════════════════════════════ COMPLETE WORKING EXAMPLE: ═══════════════════════════════════════════════════════════════════
metric_query: { "dimensions": ["my_table_date_day"], "metrics": [], "filters": { "dimensions": { "id": "root", "and": [ { "id": "filter_1", "target": {"fieldId": "my_table_country"}, "operator": "equals", "values": ["US"] }, { "id": "filter_2", "target": {"fieldId": "my_table_date_day"}, "values": [30], "operator": "inThePast", "required": false, "settings": { "completed": false, "unitOfTime": "days" } } ] } }, "sorts": [{"fieldId": "my_table_date_day", "descending": true}], "limit": 500, "tableCalculations": [], "additionalMetrics": [ { "name": "dau", "label": "Daily Active Users", "description": "Count of unique users", "type": "count_distinct", "sql": "${TABLE}.user_id", "table": "my_table", "baseDimensionName": "user_id", "formatOptions": {"type": "default", "separator": "default"} } ] }
Key Rules:
Field IDs: Use table_field format (e.g., orders_amount). Use get-explore-schema to find correct IDs.
Filters:
Simple: {"operator": "equals", "values": ["value"]}
Time: {"operator": "inThePast", "values": [7], "settings": {"unitOfTime": "days", "completed": false}}
Additional Metrics: Use this to create ad-hoc metrics (like count distinct) that aren't in the dbt model.
| Name | Required | Description | Default |
|---|---|---|---|
| explore_name | Yes | Name of the explore (table) to query (e.g., 'orders', 'customers') | |
| metric_query | Yes | JSON string of the metric query configuration. Must include 'dimensions', 'metrics', etc. See description for example. | |
| limit | No | Optional: Limit number of rows returned. Default is 500. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden of behavioral disclosure. It describes the tool as executing queries but does not explicitly state that it is read-only, idempotent, or requires specific permissions. The description includes detailed input rules but omits safety or side-effect information, which is a gap for a query tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with headings, bullet points, and a complete example. It is informative but slightly lengthy; however, each sentence adds value. Could be trimmed slightly, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description thoroughly explains input configuration but lacks information about the return format, error handling, or how to interpret results. Since there is no output schema, the description should cover what the tool returns. This gap reduces completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all three parameters. The description adds significant value beyond the schema, including a complete working example, key rules for field IDs, filter syntax, and additional metrics. This clarifies the complex 'metric_query' parameter effectively.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute a raw metric query against a Lightdash explore', specifying the verb (execute) and resource (raw metric query). It distinguishes from siblings like 'run-chart-query' by noting use cases such as ad-hoc analysis, dashboard-only charts, and debugging, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly lists when to use the tool (ad-hoc analysis, dashboard-only charts, debugging) and references 'get-explore-schema' for field IDs. However, it does not explicitly state when NOT to use it (e.g., prefer 'run-chart-query' for saved charts), though sibling tools provide context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for charts by name or description.
Performs case-insensitive partial matching against:
Chart names
Chart descriptions
Returns matching charts with their UUID, name, space, and description.
When to use:
To find charts related to a topic or metric
When you know part of a chart's name but not the exact name
To discover charts by business term (if described well)
Difference from list-charts: This searches both name AND description, while list-charts only filters by name.
| Name | Required | Description | Default |
|---|---|---|---|
| search_term | Yes | Search term to match against chart names and descriptions (case-insensitive). Example: 'user retention' will match charts with those words in name or description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full burden for behavioral disclosure. It accurately describes the search behavior (case-insensitive partial matching) and specifies return fields (UUID, name, space, description). It does not mention potential limits like pagination or result count, but for a search tool of this simplicity, the transparency is largely sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and concise: a clear first sentence, bullet points for matching fields and return fields, and separate sections for usage guidance and differentiation. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple search tool with one parameter and no output schema, the description adequately covers input, behavior, and output fields. It does not mention ordering or pagination, but this is acceptable for most use cases. The context from sibling tools supports completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides a detailed description of the 'search_term' parameter with an example. The tool description reinforces the case-insensitive and partial matching behavior but does not add substantial new meaning beyond the schema. With 100% schema coverage, baseline is 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches for charts by name or description with case-insensitive partial matching. It explicitly distinguishes from the sibling tool 'list-charts' by noting that this tool searches both name and description, while the other only filters by name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a dedicated 'When to use' section with three specific scenarios and a 'Difference from list-charts' section, providing clear guidance on when to use this tool versus alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing saved chart's configuration.
This tool allows partial updates - you only need to provide the fields you want to change.
Updatable fields:
name: Chart name
description: Chart description
metric_query: JSON string with metricQuery updates (dimensions, metrics, filters, sorts, etc.)
chart_config: JSON string with chartConfig updates (visualization settings)
pivot_config: JSON string with pivotConfig updates
Common use cases:
Change sorting: metric_query: {"sorts": [{"fieldId": "table_field_name", "descending": false}]}
Update filters: metric_query: {"filters": {"dimensions": {"id": "root", "and": [...]}}}
Change chart type: chart_config: {"type": "cartesian", "config": {...}}
Add/remove dimensions or metrics: metric_query: {"dimensions": ["dim1", "dim2"], "metrics": ["metric1"]}
Important notes:
Uses PATCH endpoint - only provided fields are updated
For metric_query updates, provide only the keys you want to change
The tool merges your updates with the existing configuration
Use get-chart-details first to see current configuration
Example - Change sort to ascending by name:
chart_identifier: "My Chart Name"
metric_query: {"sorts": [{"fieldId": "table_column_name", "descending": false}]}| Name | Required | Description | Default |
|---|---|---|---|
| chart_identifier | Yes | Chart name (exact match) or UUID to update | |
| name | No | Optional: New name for the chart | |
| description | No | Optional: New description for the chart | |
| metric_query | No | Optional: JSON string with metricQuery fields to update (e.g., sorts, filters, dimensions, metrics) | |
| chart_config | No | Optional: JSON string with chartConfig fields to update | |
| pivot_config | No | Optional: JSON string with pivotConfig to update. Use null to remove pivot. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses behavioral traits: it uses a PATCH endpoint, merges updates, and lists updatable fields. It also warns about JSON string parameters. It lacks details on error handling, rate limits, or permanence, but overall provides sufficient transparency for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections (purpose, updatable fields, common use cases, important notes, example) and uses markdown for readability. It is slightly verbose due to multiple examples, but every part earns its place for clarity. Front-loaded with the main purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, partial updates, JSON inputs) and the absence of an output schema, the description covers usage patterns, merge behavior, and prerequisite steps. It is missing a description of the return value, but overall provides a complete understanding for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage, so baseline is 3. The description significantly adds value by providing concrete examples for each parameter (e.g., changing sorts, filters, chart type) and explaining how to use JSON strings. This exceeds the baseline and helps the agent understand parameter usage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Update an existing saved chart's configuration' using a specific verb and resource. It distinguishes from sibling tools like create-chart and delete-chart by specifying partial updates and listing common use cases that differentiate it from querying or read operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains that the tool allows partial updates and provides common use cases and important notes, including recommending 'Use get-chart-details first to see current configuration.' However, it does not explicitly contrast with when to use alternative tools like run-chart-query for testing queries, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update dashboard-level filters that apply to all tiles.
Dashboard filters allow users to:
Filter all charts on a dashboard at once
Create interactive dashboards where users can change filters
Implement global date ranges or category filters
Filter configuration structure: Filters use the same structure as chart filters with:
Field references (fieldId)
Operators (equals, notEquals, contains, greaterThan, etc.)
Values or value ranges
Time-based filters (inThePast, inTheNext, etc.)
When to use:
To add global date range selectors
To create region/category filters that apply to all charts
To update filter options or defaults
To remove filters that are no longer needed
Important: Changes apply immediately to all dashboard viewers.
Testing: Use run-dashboard-chart after updating to verify filters work as expected.
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| filters | Yes | JSON string of filter configuration. Use same structure as chart filters. Example: {"dimensions": {"id": "root", "and": [{"id": "filter1", "target": {"fieldId": "table_field"}, "operator": "equals", "values": ["value"]}]}} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses that changes apply immediately to all dashboard viewers, which is a critical behavioral trait. No annotations provided, so description carries this burden. It also recommends verification via run-dashboard-chart, implying no built-in validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections (purpose, user benefits, filter structure, usage scenarios, important note, testing tip). Every sentence is informative and earns its place without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with two parameters and no output schema, the description fully explains the input format and behavior. It covers the filter structure in detail and provides usage guidance, making it complete for agent invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both parameters. The description adds value by explaining the filter configuration structure, listing supported operators and time-based filters, and providing an example JSON.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Update' and resource 'dashboard-level filters', and distinguishes from sibling tools like update-chart and update-dashboard-tile by focusing on filters that apply to all tiles.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section lists specific scenarios (e.g., adding global date range selectors, creating region/category filters). It also suggests testing after update. It does not explicitly exclude chart-specific filter updates, but the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update any properties of a tile on a dashboard.
You can modify multiple tile properties in a single operation:
Position properties (at tile level):
x, y: Change tile position
h, w: Resize tile
Display properties (in properties object):
title: Change display name
content: Update markdown content
savedChartUuid: Change which chart is displayed (for saved_chart tiles)
Any other tile-specific properties
CRITICAL - Grid System: Lightdash uses a 36-column grid horizontally:
For 2 tiles per row: w: 18 each (x: 0 and x: 18)
For 3 tiles per row: w: 12 each (x: 0, x: 12, x: 24)
For full-width tile: w: 36
When to use:
To reposition or resize tiles on a dashboard
To update multiple tile properties at once
To change content of markdown tiles
To swap which chart is displayed in a chart tile
Example properties_update values:
Two tiles per row: {"x": 0, "y": 0, "h": 6, "w": 18} and {"x": 18, "y": 0, "h": 6, "w": 18}
Full width: {"x": 0, "w": 36, "h": 6}
Reposition: {"x": 0, "y": 10}
| Name | Required | Description | Default |
|---|---|---|---|
| dashboard_name | Yes | Name of the dashboard (supports partial matching) | |
| tile_identifier | Yes | Current title of the tile or partial match to identify which tile to update | |
| properties_update | Yes | JSON object string of properties to update. Position properties (x, y, h, w) go at tile level. Other properties go in properties object. Example: {"x": 0, "y": 5, "title": "New Title", "w": 12} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses the 36-column grid system, ability to modify multiple properties in one operation, and separates position vs display properties. It does not mention permissions or reversibility but adds substantial context beyond schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with sections, bullet points, and examples. Front-loaded with main purpose. Some redundancy (repeats example values) but overall efficient and each sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description should explain return values or effects. It doesn't mention response or confirmation of update. It covers usage and parameters well but lacks output/confirmation info, making it slightly incomplete for an agent expecting feedback.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, but description adds critical meaning: explains grid system for positioning, provides multiple examples for properties_update, clarifies structure (position at tile level, display in properties object). This significantly enriches the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool updates tile properties, lists specific properties (position, display), and distinguishes from sibling tools like rename-dashboard-tile. It uses specific verbs and identifies the resource (tile on dashboard).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'When to use' section explicitly lists scenarios like repositioning, resizing, updating multiple properties, and swapping charts. It provides clear context but does not explicitly mention when not to use or name alternative tools, though inference is possible.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Most tools have clearly distinct purposes, such as create/list/get/update/delete for charts, dashboards, and spaces. However, there is potential confusion between run-chart-query and run-raw-query, and between get-dashboard-code, get-dashboard-tiles, and get-dashboard-tile-chart-config, though descriptions mitigate ambiguity.
All tool names follow a consistent verb-noun pattern with hyphens (e.g., create-chart, list-dashboards, get-explore-schema). No mixing of conventions like camelCase or snake_case, making the pattern predictable.
28 tools is on the higher side but well-justified for a BI server covering charts, dashboards, spaces, explores, queries, and projects. The count reflects comprehensive coverage without being bloated; each tool earns its place.
The tool set covers CRUD operations for charts, dashboards, spaces, explores, and queries, supporting a full lifecycle. Minor gaps include no general dashboard rename tool (though duplicate-dashboard helps) and no bulk operations, but core workflows are well-supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
A Model Context Protocol server for Wix AI tools
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Enable secure connectivity between Sentry issues and debugging data, and LLM clients, using a Model Context Protocol (MCP) server.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/poddubnyoleg/lightdash_mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
