Provides full access to Apache Superset instances, enabling AI assistants to manage dashboards, charts, datasets, databases, and execute SQL queries through Superset's API.
Click on "Deploy 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., "@superset-mcp show me the top 5 dashboards by view count"
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.
MCP (Model Context Protocol) server for Apache Superset. Gives AI assistants full access to your Superset instance — dashboards, charts, datasets, databases, and SQL execution.
uv — Python package manager
Access to a running Apache Superset instance
Related MCP server: Zaturn
git clone <repo-url>
cd superset-mcpcp .env.example .envEdit .env:
SUPERSET_URL=http://your-superset-host:8088
SUPERSET_USERNAME=your-username
SUPERSET_PASSWORD=your-passworduv run superset-mcpYou should see the MCP server start without errors. Press Ctrl+C to stop.
Replace /ABSOLUTE/PATH/TO/superset-mcp with the actual path where you cloned the repo.
Add to ~/.claude/settings.json (or project-level .claude/settings.json):
{
"mcpServers": {
"superset": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/superset-mcp", "run", "superset-mcp"],
"env": {
"SUPERSET_URL": "http://your-superset-host:8088",
"SUPERSET_USERNAME": "your-username",
"SUPERSET_PASSWORD": "your-password"
}
}
}
}Or run in terminal:
claude mcp add superset -- uv --directory /ABSOLUTE/PATH/TO/superset-mcp run superset-mcpAdd to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"superset": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/superset-mcp", "run", "superset-mcp"],
"env": {
"SUPERSET_URL": "http://your-superset-host:8088",
"SUPERSET_USERNAME": "your-username",
"SUPERSET_PASSWORD": "your-password"
}
}
}
}Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"superset": {
"command": "uv",
"args": ["--directory", "/ABSOLUTE/PATH/TO/superset-mcp", "run", "superset-mcp"],
"env": {
"SUPERSET_URL": "http://your-superset-host:8088",
"SUPERSET_USERNAME": "your-username",
"SUPERSET_PASSWORD": "your-password"
}
}
}
}Tool | Description |
| List all dashboards (with optional search) |
| Get a dashboard by ID or slug |
| Get all charts in a dashboard |
| Get all datasets used by a dashboard |
| Create a new dashboard |
| Update title, layout, metadata |
| Publish a draft dashboard |
| Duplicate a dashboard |
| Delete a dashboard |
Tool | Description |
| List all charts (with optional search) |
| Get a chart by ID or UUID |
| Fetch the latest data for a chart |
| Create a new chart |
| Update chart properties |
| Delete a chart |
Tool | Description |
| List all datasets |
| Get a dataset by ID or UUID |
| Create from a table or SQL query |
| Get existing or create new |
| Sync columns from source table |
| Update dataset properties |
| See which charts/dashboards use it |
| Delete a dataset |
Tool | Description |
| List all database connections |
| Get a database connection by ID |
| List schemas in a database |
| List tables in a schema |
| Get column info for a table |
| Get a SELECT * template for a table |
Tool | Description |
| Run a SQL query and get results |
| Pretty-print a SQL query |
| Estimate query cost (if supported) |
| List saved SQL queries |
| Save a SQL query |
Once connected to your AI assistant:
"List all published dashboards"
"Create a new dashboard called 'Sales Overview'"
"Show me all charts in dashboard 11"
"Run a SQL query on database 2: SELECT count() FROM orders"*
"What datasets are used by the 'Revenue' dashboard?"
"Create a bar chart using dataset 5 showing sales by region"
Create a copy of a dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral insight. It implies a write operation ('Create a copy') but doesn't disclose permissions needed, whether the copy is editable, what happens to the original, or any rate limits. This is inadequate for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with zero wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 an output schema (which handles return values), the description's minimalism is somewhat acceptable. However, for a mutation tool with no annotations and 0% schema coverage, it should provide more context about behavior and parameters to be fully complete.
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 0%, and the description adds no parameter information beyond what the schema name 'id_or_slug' implies. It doesn't explain what 'id_or_slug' refers to, valid formats, or examples, failing to compensate for the schema's lack of 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 the action ('Create a copy') and resource ('dashboard'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'create_dashboard' or 'duplicate_dashboard' (if present), but the verb 'copy' is specific enough to convey distinct 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?
The description provides no guidance on when to use this tool versus alternatives like 'create_dashboard' or other dashboard-related tools. It lacks context about prerequisites (e.g., needing an existing dashboard) or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new chart.
| Name | Required | Description | Default |
|---|---|---|---|
| slice_name | Yes | Chart name | |
| viz_type | Yes | Visualization type (e.g. 'bar', 'line', 'pie', 'table', 'big_number_total') | |
| datasource_id | Yes | ID of the dataset to use | |
| datasource_type | No | 'table' for datasets (default) | table |
| params | No | JSON string of chart parameters/query context | {} |
| description | No | Optional chart description | |
| dashboards | No | List of dashboard IDs to add the chart to |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Create a new chart' implies a write operation, but it doesn't disclose any behavioral traits such as required permissions, whether the chart is saved persistently, potential side effects (e.g., adding to dashboards), rate limits, or error conditions. This leaves significant gaps for an agent to understand how the tool behaves.
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 extremely concise with a single sentence 'Create a new chart.', which is front-loaded and wastes no words. While it may be under-specified, it earns full marks for brevity and clarity within its limited scope.
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, write operation) and the presence of an output schema (which reduces the need to describe return values), the description is minimally adequate but incomplete. It lacks context about the chart's lifecycle, integration with dashboards, or error handling, making it insufficient for full understanding despite the structured data support.
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%, so the schema already documents all 7 parameters thoroughly. The description adds no additional meaning beyond what the schema provides—it doesn't explain parameter relationships, default behaviors, or practical usage examples. With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.
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 'Create a new chart' clearly states the action (create) and resource (chart), but it's vague about what constitutes a chart in this context and doesn't distinguish it from sibling tools like 'create_dashboard' or 'create_dataset'. It provides basic purpose but lacks specificity about the chart's nature or scope.
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?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't explain when to choose 'create_chart' over 'update_chart' or how it relates to 'create_dashboard' or 'create_dataset'. The description offers no context about prerequisites, dependencies, or typical use cases.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| slug | No | ||
| published | No | ||
| json_metadata | No | ||
| position_json | No |
| Name | Required | Description |
|---|---|---|
No output 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. 'Create a new dashboard' implies a write operation, but it doesn't disclose permissions needed, side effects, rate limits, or what the creation entails (e.g., whether it's immediately visible). This is a significant gap for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with zero waste. It's appropriately sized and front-loaded, making it easy to parse quickly. Every word earns its place, though it could benefit from more detail.
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 (5 parameters, 1 required, no annotations) and the presence of an output schema, the description is incomplete. It doesn't explain parameters or behavioral traits, but the output schema might cover return values. For a creation tool with multiple parameters, more context is needed to be fully helpful.
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 0%, so the description must compensate by explaining parameters. It adds no meaning beyond the schema—it doesn't clarify what 'title', 'slug', 'published', 'json_metadata', or 'position_json' do, their formats, or examples. With 5 parameters and low coverage, this is inadequate.
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 'Create a new dashboard' clearly states the action (create) and resource (dashboard), but it's vague about what a dashboard entails in this context and doesn't differentiate from sibling tools like 'create_chart' or 'create_dataset' beyond the resource name. It meets the basic requirement of stating what the tool does without being tautological.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, when not to use it, or how it relates to siblings like 'copy_dashboard', 'update_dashboard', or 'publish_dashboard'. The agent must infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a dataset from a table or SQL query.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ID of the database connection | |
| table_name | Yes | Table name (or virtual dataset name if sql provided) | |
| schema | No | Schema name | |
| sql | No | SQL query for virtual datasets (optional) | |
| is_managed_externally | No | Whether the dataset is managed externally |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool creates a dataset but doesn't cover critical aspects like permissions required, whether the operation is idempotent, potential side effects (e.g., on existing datasets), or error handling. This leaves significant gaps 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 a single, efficient sentence that directly states the tool's purpose without any fluff or redundancy. It is appropriately sized and front-loaded, making it easy for an agent to parse quickly.
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 that there is an output schema (which handles return values) and full schema description coverage, the description is minimally adequate. However, as a mutation tool with no annotations, it should provide more behavioral context (e.g., permissions, idempotency) to be fully complete, leaving room for improvement.
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%, so the schema fully documents all parameters. The description adds no additional meaning beyond implying that 'sql' can be used for virtual datasets, which is already covered in the schema's description for 'table_name' and 'sql'. This meets the baseline for high schema coverage.
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 ('Create a dataset') and the source ('from a table or SQL query'), which is specific and actionable. However, it doesn't differentiate from sibling tools like 'get_or_create_dataset' or 'update_dataset', which would require explicit comparison to achieve a score of 5.
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 no guidance on when to use this tool versus alternatives like 'get_or_create_dataset' or 'update_dataset'. It lacks context about prerequisites, such as needing an existing database connection, and doesn't mention any exclusions or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a chart by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states 'Delete' but gives no information on permissions required, whether deletion is reversible, what happens to associated data, or error handling. This is inadequate for a destructive operation with zero annotation coverage.
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 extremely concise with a single sentence that directly states the tool's function. It's front-loaded and wastes no words, making it easy to parse quickly.
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 destructive nature, no annotations, and an output schema (which might cover return values), the description is insufficient. It doesn't address critical aspects like safety, side effects, or prerequisites, leaving significant gaps for an AI agent to understand proper usage.
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 0%, so the description must compensate, but it only mentions 'by ID' without explaining what 'pk' represents or its format. It adds minimal meaning beyond the schema's property name. With one parameter, the baseline is 4, but the lack of detail reduces it to 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 action ('Delete') and target resource ('a chart by ID'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling deletion tools like delete_dashboard or delete_dataset, which follow the same pattern, so it misses the highest score.
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 no guidance on when to use this tool versus alternatives. With siblings like delete_dashboard and delete_dataset, there's no indication of context or prerequisites, such as needing to retrieve a chart ID first or checking dependencies. It's a bare statement with no usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a dashboard by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output 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 states the action ('Delete') but doesn't mention critical details like whether deletion is permanent, requires specific permissions, has side effects (e.g., on related charts), or what the output schema indicates. This is inadequate for a destructive 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 extremely concise—a single sentence with no wasted words—and front-loaded with the core action. It efficiently communicates the essential information without unnecessary elaboration.
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 a destructive operation, no annotations, and 0% schema description coverage, the description is insufficient. While an output schema exists, the description doesn't address behavioral risks, prerequisites, or sibling tool distinctions, making it incomplete for safe and effective 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?
The description adds minimal semantics by specifying that 'pk' corresponds to a dashboard ID, which is useful since schema description coverage is 0%. However, it doesn't explain what 'pk' stands for (e.g., primary key) or provide format/validation details, leaving gaps despite the single parameter.
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 ('Delete') and resource ('a dashboard by ID'), making the purpose unambiguous. However, it doesn't differentiate from sibling tools like 'delete_chart' or 'delete_dataset' beyond specifying the resource type, which is a minor gap.
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 no guidance on when to use this tool versus alternatives, such as when to delete a dashboard instead of updating it or when deletion is irreversible. With multiple sibling tools (e.g., 'delete_chart', 'update_dashboard'), this lack of context is a significant omission.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a dataset by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states the action ('Delete') which implies a destructive mutation, but doesn't cover critical aspects like permissions needed, irreversibility, side effects (e.g., impact on related objects), or error handling. This is a significant gap for a destructive 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 a single, direct sentence with zero wasted words. It's appropriately sized and front-loaded, immediately conveying the core action without unnecessary elaboration.
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 destructive nature, lack of annotations, and presence of an output schema, the description is minimally adequate. It states what the tool does but doesn't address safety, context, or alternatives. The output schema may cover return values, but the description should do more for a mutation 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?
The description mentions 'by ID' which clarifies that the 'pk' parameter is a dataset identifier, adding meaning beyond the schema's basic integer type. However, with 0% schema description coverage and only one parameter, this minimal addition meets the baseline for adequate but not comprehensive parameter explanation.
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 ('Delete') and the resource ('a dataset by ID'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'delete_chart' or 'delete_dashboard' beyond specifying the resource type, which keeps it from a perfect score.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., dataset must exist), exclusions, or compare with related tools like 'delete_chart' or 'delete_dashboard', leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the cost of running a SQL query (supported databases only).
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ||
| sql | Yes | ||
| schema | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'supported databases only', adding some context about limitations, but fails to disclose critical behavioral traits such as whether this is a read-only operation, if it requires specific permissions, potential rate limits, or what the output entails (e.g., cost units, accuracy). For a tool with no annotations, this is insufficient.
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 a single, efficient sentence with zero waste—it directly states the tool's function and a key limitation. It is appropriately sized and front-loaded, making it easy to parse quickly without unnecessary elaboration.
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 (cost estimation with 3 parameters) and no annotations, the description is incomplete—it lacks details on parameters, behavioral traits, and usage context. However, the presence of an output schema mitigates some need to explain return values. Overall, it's minimally adequate but has clear 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 description coverage is 0%, so the description must compensate by explaining parameters. It only implies 'SQL query' and 'databases' without detailing the three parameters (database_id, sql, schema). No meaning is added beyond what the schema names suggest, leaving parameters largely undocumented and unclear in 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 the verb ('estimate') and resource ('cost of running a SQL query'), making the purpose specific and understandable. It distinguishes from siblings like execute_sql (which runs queries) by focusing on cost estimation rather than execution. However, it doesn't fully differentiate from all siblings (e.g., format_sql also processes SQL).
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 minimal guidance with 'supported databases only', which hints at limitations but doesn't specify when to use this tool versus alternatives like execute_sql for actual query execution. No explicit when/when-not scenarios or prerequisite checks are mentioned, leaving usage context vague.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SQL query and return results.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ID of the database to query | |
| sql | Yes | SQL query to execute | |
| schema | No | Schema/database to run the query in | |
| limit | No | Maximum number of rows to return (default 100) |
| Name | Required | Description |
|---|---|---|
No output 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 mentions execution and returning results but lacks critical details: whether queries can be read-only or include writes, authentication requirements, rate limits, error handling, or the format of returned results. For a SQL execution tool with zero annotation coverage, this is a significant gap.
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 extremely concise and front-loaded: 'Execute a SQL query and return results.' It's a single, efficient sentence with zero waste, making it easy to parse quickly. Every word earns its place by conveying the core functionality.
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 (executing arbitrary SQL) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete behavioral context, it leaves gaps in understanding safety, permissions, and operational constraints, making it only partially complete for effective agent 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 description coverage is 100%, so the schema already documents all four parameters (database_id, sql, schema, limit) with clear descriptions. The description adds no additional meaning beyond what's in the schema, such as query syntax examples or schema usage context. Baseline 3 is appropriate when the schema does the heavy lifting.
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's purpose: 'Execute a SQL query and return results.' It specifies the verb ('execute') and resource ('SQL query'), making it easy to understand what the tool does. However, it doesn't differentiate from sibling tools like 'format_sql' or 'estimate_query_cost', which are related but distinct 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 provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid database ID), exclusions (e.g., not for data modification queries), or comparisons with siblings like 'format_sql' (for formatting) or 'estimate_query_cost' (for cost estimation).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Format/pretty-print a SQL query.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden for behavioral disclosure. It states the action but doesn't explain what formatting entails (e.g., indentation, capitalization rules), whether it validates SQL syntax, handles errors, or has performance implications. This leaves significant gaps for a tool that modifies input.
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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded and wastes no space, making it highly concise and well-structured for quick understanding.
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 moderate complexity (formatting SQL), no annotations, and an output schema that likely handles return values, the description is minimally adequate. It covers the core action but lacks details on behavior, parameters, and usage context, making it incomplete for full agent guidance.
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 0% description coverage, with one parameter 'sql' undocumented. The description implies 'sql' is a SQL query to format, adding basic meaning beyond the schema. However, it doesn't specify format requirements (e.g., plain text, supported dialects), so it only partially compensates for the schema gap.
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's purpose with a specific verb ('format/pretty-print') and resource ('SQL query'), making it immediately understandable. However, it doesn't distinguish this formatting tool from sibling tools like execute_sql or save_query, which prevents a perfect score.
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 no guidance on when to use this tool versus alternatives. With siblings like execute_sql and save_query that might also handle SQL queries, there's no indication of when formatting is preferred over execution or saving, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a chart by ID or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_uuid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool 'Get[s] a chart', implying a read-only operation, but doesn't disclose behavioral traits such as authentication requirements, error handling (e.g., for invalid IDs), rate limits, or response format. This leaves gaps in understanding how the tool behaves beyond its basic purpose.
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 a single, efficient sentence with zero waste: 'Get a chart by ID or UUID.' It front-loads the core action and key detail (ID/UUID), making it easy to parse. Every word contributes directly to understanding the tool's 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 low complexity (1 parameter, no nested objects) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete parameter documentation, it lacks details on usage context, errors, or behavioral nuances, making it incomplete for fully informed tool selection.
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 1 parameter with 0% description coverage, so the description must compensate. It mentions 'by ID or UUID', adding meaning about the parameter's purpose (identifying a chart) and acceptable types (string or integer). However, it doesn't explain format specifics (e.g., UUID structure) or constraints, leaving the parameter partially documented.
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 ('Get') and resource ('a chart'), specifying it's by 'ID or UUID'. It distinguishes from siblings like 'list_charts' (which lists multiple) and 'get_chart_data' (which retrieves data rather than metadata). However, it doesn't explicitly differentiate from 'get_dashboard' or 'get_dataset', which are similar retrieval operations for different resources.
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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid ID/UUID), contrast with 'list_charts' for browsing, or specify scenarios like retrieving metadata versus data (vs. 'get_chart_data'). The description is purely functional without contextual advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch the latest data for a chart.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'latest data' but doesn't disclose behavioral traits like whether this is a read-only operation, if it requires specific permissions, rate limits, or how 'latest' is defined (e.g., cached vs. real-time). The description is minimal and lacks critical operational 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 concise with a single sentence, but it's under-specified rather than efficiently informative. It's front-loaded with the core action but lacks necessary elaboration, making it borderline between brevity and insufficiency.
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 an output schema (which reduces the need to describe return values) but no annotations and poor parameter coverage, the description is incomplete. It covers the basic purpose but misses usage guidelines, parameter semantics, and behavioral details needed for effective tool selection and 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 description coverage is 0%, and the description provides no parameter information. It doesn't explain what 'pk' means (e.g., primary key, chart ID) or its format, leaving the single required parameter undocumented. The description fails to compensate for the schema's lack of details.
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's purpose ('Fetch the latest data for a chart') with a clear verb ('Fetch') and resource ('chart data'), but it's vague about scope and doesn't distinguish from siblings like 'get_chart' or 'list_charts'. It lacks specificity on what 'latest data' entails compared to other chart-related tools.
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?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'get_chart', 'list_charts', and 'update_chart', the description offers no context for selection, such as whether this is for raw data versus metadata or real-time versus cached data.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a single dashboard by ID or slug.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the basic operation. It doesn't disclose behavioral traits like read-only nature (implied by 'Get'), error handling for invalid IDs/slugs, authentication needs, rate limits, or response format details.
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 a single, efficient sentence with zero waste, front-loading the core purpose. Every word earns its place without redundancy or unnecessary elaboration.
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 single-parameter input and existence of an output schema, the description is minimally adequate but lacks context on prerequisites, error cases, or sibling tool differentiation. For a basic read operation, it meets the minimum viable threshold but leaves room for improvement.
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 0%, but the description adds meaning by explaining that the parameter accepts 'ID or slug', clarifying the dual input types beyond the schema's anyOf string/integer. However, it doesn't detail format constraints or examples, leaving gaps in parameter understanding.
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 ('Get') and resource ('a single dashboard'), specifying retrieval by ID or slug. It distinguishes from sibling list_dashboards by focusing on single-item retrieval, though it doesn't explicitly contrast with get_dashboard_charts or other get_* tools.
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?
No guidance on when to use this tool versus alternatives like list_dashboards for browsing or get_dashboard_charts for related data. The description implies usage for single-dashboard retrieval but lacks explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all charts in a dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Get all charts in a dashboard,' which implies a read-only operation, but doesn't specify permissions, rate limits, pagination, or what 'get' returns (e.g., chart objects, metadata). This leaves significant gaps in understanding 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 a single, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it highly efficient and easy to parse.
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 low complexity (one parameter) and the presence of an output schema (which handles return values), the description is minimally adequate. However, with no annotations and incomplete parameter guidance, it lacks details on behavioral aspects like permissions or error handling, making it incomplete for full contextual 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?
The description mentions 'in a dashboard,' which implies the parameter 'id_or_slug' identifies a dashboard, adding context beyond the schema's 0% coverage. However, it doesn't explain the parameter's format (string vs. integer) or provide examples. With one parameter and low schema coverage, this partial compensation earns a baseline score.
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 ('Get') and resource ('all charts in a dashboard'), making the purpose understandable. It distinguishes from siblings like 'get_chart' (single chart) and 'list_charts' (all charts across dashboards), though not explicitly. However, it lacks specificity about what 'get' entails (e.g., metadata vs. data), preventing a perfect score.
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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention siblings like 'get_chart' (for a single chart) or 'list_charts' (for all charts), nor does it specify prerequisites or contexts for usage. The description is too minimal to imply any usage rules.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all datasets used by a dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_slug | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states a read operation ('Get'), implying it's likely non-destructive, but doesn't specify permissions required, rate limits, pagination, or what the output contains. This leaves significant gaps for a tool that interacts with data resources.
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 a single, efficient sentence that directly states the tool's function without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 an output schema, the description doesn't need to explain return values. However, with no annotations, 1 parameter at 0% schema coverage, and moderate complexity (fetching datasets for a dashboard), the description is minimal but adequate as a basic overview, though it could benefit from more behavioral or usage details.
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 mentions 'a dashboard' which implies the 'id_or_slug' parameter refers to a dashboard identifier, adding some meaning beyond the schema's 0% coverage. However, it doesn't clarify the format or constraints of 'id_or_slug', such as whether it's numeric or string-based, so it only partially compensates for the low schema coverage.
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 ('Get') and target resource ('all datasets used by a dashboard'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'get_dataset' or 'list_datasets', which might retrieve datasets in other contexts, so it doesn't reach the highest clarity level.
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 no guidance on when to use this tool versus alternatives like 'get_dataset' or 'list_datasets'. It lacks context about prerequisites, such as needing a dashboard identifier, or exclusions, leaving the agent to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a database connection by ID.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states a read operation ('Get'), implying it's likely safe, but doesn't specify if it requires authentication, returns error details, or has rate limits. This is a significant gap for a tool with zero annotation coverage.
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 a single, efficient sentence with zero waste, front-loading the core action and resource. It's appropriately sized for a simple retrieval tool, making it easy to parse quickly.
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 low complexity (one parameter) and the presence of an output schema (which handles return values), the description is somewhat complete but lacks key context. It doesn't cover behavioral aspects like error handling or prerequisites, making it adequate but with clear gaps for informed 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?
The description adds minimal meaning beyond the input schema: it clarifies that 'pk' refers to a database connection ID. However, with 0% schema description coverage, the parameter is undocumented in the schema, and the description doesn't fully compensate by explaining format (e.g., integer range) or constraints, so it only partially addresses the gap.
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 ('Get') and resource ('a database connection by ID'), making the purpose understandable. However, it doesn't distinguish this tool from similar siblings like 'get_dashboard' or 'get_dataset', which follow the same 'get X by ID' pattern, so it misses full differentiation.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid database ID), exclusions, or comparisons to siblings like 'list_databases' for browsing or 'get_dataset' for other resources, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a dataset by ID or UUID.
| Name | Required | Description | Default |
|---|---|---|---|
| id_or_uuid | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states a read operation ('Get'), implying it's non-destructive, but doesn't disclose behavioral traits like authentication needs, rate limits, error handling, or what 'Get' entails (e.g., returns metadata, full data, or a reference). This is inadequate for a tool with no annotation coverage.
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 a single, efficient sentence with zero waste—'Get a dataset by ID or UUID.' It's front-loaded and appropriately sized for a simple retrieval tool, earning full marks for conciseness.
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 1 parameter, no annotations, and an output schema exists (so return values needn't be explained), the description is minimally complete. It covers the basic purpose but lacks usage guidelines and behavioral details, making it adequate yet with clear gaps for effective tool 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 description coverage is 0%, so the description must compensate. It adds meaning by specifying the parameter accepts 'ID or UUID', clarifying it's not just any string/integer. However, it doesn't explain format, examples, or constraints beyond the schema's basic types, leaving gaps. With 1 parameter and low coverage, this is a minimal but not sufficient improvement.
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 ('Get') and resource ('a dataset'), specifying retrieval by ID or UUID. It distinguishes from siblings like list_datasets (which lists multiple) and get_dataset_related_objects (which fetches related items), though not explicitly. However, it lacks explicit sibling differentiation, preventing a perfect score.
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?
No guidance is provided on when to use this tool versus alternatives. For example, it doesn't mention using list_datasets to find IDs first or get_or_create_dataset for conditional retrieval. The description implies usage by stating 'by ID or UUID' but offers no context or exclusions, leaving gaps for agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get an existing dataset or create it if it doesn't exist.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ||
| table_name | Yes | ||
| schema | No |
| Name | Required | Description |
|---|---|---|
No output 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 mentions the conditional behavior ('get or create'), but fails to detail critical aspects such as permissions required, whether creation is automatic or requires confirmation, error handling, or what happens if parameters conflict with existing datasets. This is inadequate for a mutation-capable 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 a single, clear sentence that efficiently conveys the core functionality without unnecessary words. It's front-loaded and every part earns its place, making it highly concise and well-structured.
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 (conditional get/create with 3 parameters), lack of annotations, and 0% schema coverage, the description is insufficient. While an output schema exists, the description doesn't address parameter meanings, behavioral nuances, or usage distinctions from siblings, leaving significant gaps for an AI 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?
Schema description coverage is 0%, meaning parameters are undocumented in the schema. The description adds no information about what 'database_id', 'table_name', or 'schema' represent, their formats, or how they influence the get/create logic. It doesn't compensate for the lack of schema documentation, falling short of the 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?
The description clearly states the tool's purpose: 'Get an existing dataset or create it if it doesn't exist.' It specifies the verb ('get or create') and resource ('dataset'), making the action unambiguous. However, it doesn't explicitly differentiate from sibling tools like 'get_dataset' or 'create_dataset', which would require a 5.
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 implies usage context—when you need a dataset and are unsure if it exists—but doesn't provide explicit guidance on when to use this tool versus alternatives like 'get_dataset' or 'create_dataset'. No exclusions or prerequisites are mentioned, leaving room for ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a SELECT * query for a table (with schema).
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ||
| table_name | Yes | ||
| schema | No |
| Name | Required | Description |
|---|---|---|
No output 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 states the tool returns a SELECT * query, but doesn't explain what the output looks like (e.g., SQL string, formatted result), whether it includes error handling, or if it requires specific permissions. This leaves gaps in understanding how the tool behaves beyond its basic purpose.
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 extremely concise and front-loaded in a single sentence: 'Get a SELECT * query for a table (with schema).' Every word contributes directly to the purpose, with no wasted information, making it easy to parse quickly.
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 moderate complexity (3 parameters, no annotations, but has an output schema), the description is minimally adequate. It states the core purpose but lacks details on usage, parameters, and behavior. The presence of an output schema reduces the need to explain return values, but overall completeness is limited due to missing contextual guidance.
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 0%, meaning parameters are undocumented in the schema. The description mentions 'table (with schema)', implying the 'schema' parameter relates to table schema, but doesn't clarify its role or format. It doesn't explain 'database_id' or 'table_name' beyond what's inferred, failing to compensate for the lack of schema documentation.
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's purpose: 'Get a SELECT * query for a table (with schema).' It specifies the verb ('Get'), resource ('SELECT * query'), and scope ('for a table with schema'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from siblings like 'get_table_metadata' or 'execute_sql', which could provide similar or overlapping 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?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing a valid database_id and table_name, or compare it to siblings like 'get_table_metadata' (which might return metadata without a query) or 'execute_sql' (which runs queries). Without such context, users might struggle to choose the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get column metadata for a table.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ||
| table_name | Yes | ||
| schema | No | default |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read-only operation, it doesn't specify whether this requires specific permissions, what format the metadata returns, or if there are rate limits. The description is too minimal to adequately inform about behavioral traits beyond the basic read implication.
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 extremely concise with just 5 words, front-loading the core purpose without any wasted words. Every word earns its place, making it easy to parse while conveying the essential function.
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 an output schema (which should document return values) and relatively simple parameters, the description is minimally adequate for a read-only metadata tool. However, with no annotations and 0% schema coverage, it leaves significant gaps in understanding parameter requirements and behavioral context that the description doesn't address.
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 0% schema description coverage for all 3 parameters, the description adds no semantic information about what 'database_id', 'table_name', or 'schema' represent. It doesn't explain what a valid database_id looks like, what format table_name should be in, or what the 'schema' parameter defaults to. The description fails to compensate for the complete lack of schema documentation.
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 ('Get') and resource ('column metadata for a table'), making the purpose immediately understandable. It distinguishes this as a metadata retrieval tool rather than data retrieval or manipulation, though it doesn't explicitly differentiate from sibling tools like 'list_tables' or 'get_database'.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites like needing a valid database_id, nor does it suggest when to choose this over similar tools like 'list_tables' or 'get_database' for understanding table structure.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List charts. Optionally filter by name.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions optional filtering by name but doesn't describe pagination behavior (though parameters suggest it), authentication requirements, rate limits, error conditions, or what the output looks like. For a list operation with pagination parameters, this leaves significant behavioral gaps.
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 extremely concise at just 7 words total. It's front-loaded with the core purpose ('List charts') followed by the key optional functionality. Every word earns its place with zero wasted verbiage or 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?
Given that there's an output schema (which should document return values), the description's job is reduced. However, for a tool with 3 parameters, 0% schema description coverage, and no annotations, the description should do more to explain the pagination behavior and filtering capabilities. It's minimally adequate but leaves the agent to infer too much.
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 mentions 'Optionally filter by name' which corresponds to the 'search' parameter, providing some semantic context beyond the 0% schema description coverage. However, it doesn't explain the pagination parameters ('page' and 'page_size') or their default values/interactions. With 3 parameters and 0% schema coverage, the description adds some but insufficient 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 states the tool's purpose as 'List charts' which is a clear verb+resource combination, but it doesn't distinguish this from sibling tools like 'list_dashboards' or 'list_datasets' that follow the same pattern. The optional filtering by name adds some specificity but doesn't create meaningful differentiation from other list tools.
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 no guidance about when to use this tool versus alternatives. There's no mention of when this tool should be chosen over 'get_chart' (for retrieving a specific chart) or how it relates to 'list_dashboards' which might contain charts. The optional filtering hint is basic functionality description, not usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List dashboards. Optionally filter by title with search.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions optional filtering but doesn't describe pagination behavior (though schema shows page/page_size), rate limits, authentication needs, or what happens with empty results. For a list tool with zero annotation coverage, this leaves significant behavioral gaps.
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 extremely concise - just two short sentences with zero waste. It's front-loaded with the core purpose and efficiently adds the filtering capability. Every word earns its place in this minimal description.
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 moderate complexity (list operation with filtering and pagination), no annotations, and the presence of an output schema, the description is minimally adequate. The output schema existence means return values don't need explanation, but the description should do more to explain behavioral aspects and parameter usage given the complete lack of annotation coverage.
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 0% schema description coverage, the description must compensate. It explains the 'search' parameter's purpose ('filter by title'), which adds meaningful semantics beyond the bare schema. However, it doesn't mention the pagination parameters (page/page_size) or their default values, leaving some parameters undocumented.
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's purpose ('List dashboards') which is clear but basic. It doesn't differentiate from sibling tools like 'list_charts' or 'list_datasets' beyond specifying the resource type. The optional filtering mention adds some specificity but doesn't fully distinguish it from other list tools.
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 minimal guidance - it mentions optional filtering by title but gives no context about when to use this tool versus alternatives like 'get_dashboard' for specific dashboards or other list tools for different resources. No explicit when/when-not guidance or sibling tool comparisons are included.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all database connections configured in Superset.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the action but does not disclose behavioral traits such as pagination behavior (implied by parameters but not explained), authentication needs, rate limits, or what the output includes. This is inadequate for a tool with parameters and no annotation coverage.
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 a single, clear sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it efficient and easy to understand.
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 an output schema, the description need not explain return values. However, with no annotations, 2 parameters, and 0% schema description coverage, the description is too minimal—it lacks context on usage, behavior, or parameter meaning, making it incomplete for effective agent 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 description coverage is 0%, so the description must compensate, but it adds no parameter information. The baseline is 3 because the schema fully defines the parameters (page and page_size with defaults), and the description does not contradict it, but it fails to explain their purpose or usage in listing databases.
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 'List' and the resource 'all database connections configured in Superset,' which is specific and unambiguous. However, it does not explicitly differentiate from siblings like 'list_schemas' or 'list_tables,' which might list related but different resources, so it misses full sibling distinction.
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 no guidance on when to use this tool versus alternatives. For example, it does not mention if this is for browsing connections versus using 'get_database' for details, or how it relates to other listing tools like 'list_schemas.' This lack of context leaves usage unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List datasets (virtual or physical tables).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| search | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states the action without behavioral details. It doesn't disclose if this is read-only, paginated, requires authentication, has rate limits, or what the output entails, leaving significant gaps in understanding tool 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 very concise with a single sentence that is front-loaded and to the point. However, it could be more structured by including key details like pagination or search functionality, though it avoids 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 the tool has an output schema, the description doesn't need to explain return values, but it lacks context for a list operation with parameters. With no annotations and low schema coverage, it's minimally adequate but incomplete for guiding effective use, especially compared to siblings.
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 0%, and the description adds no parameter information beyond what the schema provides. It doesn't explain the meaning of 'page', 'page_size', or 'search' parameters, failing to compensate for the low coverage and leaving parameters undocumented.
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 action ('List') and resource ('datasets'), specifying they can be 'virtual or physical tables', which clarifies scope. However, it doesn't differentiate from siblings like 'list_tables' or 'get_dataset', making the purpose somewhat vague in context.
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?
No guidance is provided on when to use this tool versus alternatives such as 'list_tables' or 'get_dataset'. The description lacks context about use cases, prerequisites, or exclusions, offering only basic functional information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List saved SQL queries.
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'List' implies a read operation, but it doesn't specify authentication requirements, rate limits, pagination behavior (though hinted by parameters), or what the output contains. For a tool with parameters and output schema, this leaves significant behavioral gaps.
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 a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and uses straightforward language. Every word earns its place, making it easy to parse quickly.
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 moderate complexity (2 parameters, output schema exists), the description is minimally adequate. The output schema reduces the need to explain return values, but the description lacks context about the listing scope, authentication, or how it relates to sibling tools. It's complete enough for basic understanding but leaves gaps for effective 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 description coverage is 0%, so the description must compensate, but it provides no parameter information. The schema shows pagination parameters (page, page_size), but the description doesn't mention pagination at all. Since there are only 2 parameters and an output schema exists, this meets the baseline but doesn't add meaningful semantics.
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 'List saved SQL queries' clearly states the verb ('List') and resource ('saved SQL queries'), making the purpose immediately understandable. It distinguishes from siblings like 'execute_sql' or 'save_query' by focusing on listing rather than executing or creating. However, it doesn't specify scope (e.g., all queries or filtered) which prevents a perfect score.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for listing queries, or differentiate from similar tools like 'get_select_star' or 'list_tables'. Without any usage context, the agent must infer when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all schemas in a database.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states it's a listing operation, implying read-only behavior, but doesn't mention any constraints like pagination, rate limits, permissions required, or what the output contains. This leaves significant gaps for a tool with one required parameter.
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 a single, clear sentence with no wasted words. It's front-loaded with the core action and resource, making it easy to parse quickly.
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 an output schema (which handles return values), one simple parameter, and no annotations, the description is minimally adequate. However, it lacks context about the database environment, error conditions, or how results are structured, which could be helpful despite the 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?
The schema description coverage is 0%, so the description must compensate. It implies a 'database_id' parameter by mentioning 'in a database', but doesn't explain what this ID represents, its format, or where to obtain it. This adds minimal semantic value beyond what the bare 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 the verb ('List') and resource ('all schemas in a database'), making the tool's purpose immediately understandable. However, it doesn't distinguish itself from sibling tools like 'list_tables' or 'list_datasets', which follow similar patterns for different resources.
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 no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a valid database_id), exclusions, or how it differs from related listing tools like 'list_tables' or 'list_datasets' in the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tables in a database schema.
| Name | Required | Description | Default |
|---|---|---|---|
| database_id | Yes | ||
| schema | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it's a listing operation but doesn't mention whether it's read-only, safe, paginated, or has any rate limits. For a tool with zero annotation coverage, this leaves significant behavioral gaps unaddressed.
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 a single, efficient sentence that states the core purpose without any wasted words. It's appropriately sized for a simple listing tool and front-loads the essential 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 tool's low complexity (simple listing operation) and the existence of an output schema (which handles return values), the description is minimally complete. However, with no annotations and poor parameter documentation, it doesn't provide enough context for optimal agent 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 description coverage is 0%, so the description must compensate, but it only mentions 'database schema' which partially relates to the 'schema' parameter. It doesn't explain what 'database_id' represents or provide context for either parameter. The baseline is 3 since the description adds minimal value beyond the bare 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 verb ('List') and resource ('tables in a database schema'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_datasets' or 'list_schemas', which also list database objects, so it doesn't reach the highest clarity level.
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 no guidance on when to use this tool versus alternatives like 'list_datasets' or 'list_schemas'. It doesn't mention prerequisites, exclusions, or specific contexts where this tool is preferred over other listing tools in the server.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Set a dashboard as published.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It implies a mutation ('Set as published') but doesn't specify permissions needed, whether the action is reversible, or any side effects. This is inadequate for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with no wasted words. It is appropriately sized and front-loaded, making it easy to parse quickly.
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 an output schema (which handles return values) and only one parameter, the description is minimally complete but lacks critical context for a mutation tool. It covers the basic action but misses behavioral details and parameter semantics, making it only 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 description coverage is 0%, so the description must compensate but adds no information about the 'pk' parameter. It doesn't explain what 'pk' represents (e.g., primary key of a dashboard) or its format, leaving the parameter undocumented.
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 ('Set as published') and resource ('dashboard'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'update_dashboard' which might also affect publication status, so it doesn't reach the highest score.
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 no guidance on when to use this tool versus alternatives like 'update_dashboard' or prerequisites such as needing an existing unpublished dashboard. It merely states what the tool does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Refresh the dataset's columns and metrics from the source.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It implies a mutation ('refresh'), but doesn't disclose behavioral traits such as required permissions, whether it's idempotent, rate limits, or what happens during the refresh process. This leaves critical operational details unspecified for a tool that likely modifies data.
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 a single, efficient sentence with zero waste. It's front-loaded and appropriately sized, avoiding unnecessary elaboration while stating the core action clearly.
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 a refresh operation, no annotations, and 0% schema coverage, the description is incomplete. It doesn't explain the mutation's effects, error conditions, or the output schema's content. For a tool with one required parameter and likely side effects, more detail is needed to guide effective 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 description coverage is 0%, so the description must compensate. It mentions no parameters, failing to explain the 'pk' input's meaning or role in refreshing the dataset. Without this, the agent lacks context for proper invocation, making the tool harder to use 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 states the action ('refresh') and target ('dataset's columns and metrics from the source'), which is clear but vague. It doesn't specify what 'refresh' entails operationally or how it differs from sibling tools like 'update_dataset' or 'get_dataset', leaving room for ambiguity about its distinct purpose.
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?
No guidance is provided on when to use this tool versus alternatives. With siblings like 'update_dataset' and 'get_dataset', the description lacks context on prerequisites, timing, or exclusions, offering no help for an agent to choose correctly among related dataset operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a SQL query.
| Name | Required | Description | Default |
|---|---|---|---|
| label | Yes | ||
| sql | Yes | ||
| database_id | Yes | ||
| schema | No | ||
| description | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. 'Save a SQL query' implies a write operation that creates a persistent resource, but it doesn't disclose critical behaviors: whether this requires specific permissions, if saved queries can be overwritten, what happens on duplicate labels, rate limits, or what the output contains. For a mutation tool with zero annotation coverage, this is a significant gap.
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 a single, efficient sentence with zero wasted words. It's appropriately sized for a simple action and front-loaded with the core purpose. Every word earns its place, making it easy to parse quickly.
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 5 parameters with 0% schema coverage and no annotations, but does have an output schema (which reduces the need to describe return values), the description is incomplete. It covers the basic action but misses parameter explanations, usage context, and behavioral details needed for a mutation tool. The output schema helps, but gaps remain significant.
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 0%, so the description must compensate by explaining parameters, but it adds no parameter information beyond what's implied by 'SQL query' (hinting at 'sql' parameter). It doesn't clarify the purpose of 'label', 'database_id', 'schema', or 'description', leaving 5 parameters essentially undocumented. This fails to compensate for the schema's lack of 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 'Save a SQL query' clearly states the verb ('Save') and resource ('a SQL query'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'list_saved_queries' or 'execute_sql', which would require mentioning this specifically creates a persistent saved query object rather than executing or listing queries.
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 no guidance on when to use this tool versus alternatives. There's no mention of prerequisites (like needing a valid database_id), when not to use it (e.g., for temporary queries), or how it differs from similar tools like 'execute_sql' (which runs queries) or 'list_saved_queries' (which retrieves saved ones).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a chart's properties.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes | ||
| slice_name | No | ||
| description | No | ||
| viz_type | No | ||
| params | No | ||
| cache_timeout | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states this is an update operation but doesn't mention permissions needed, whether changes are reversible, rate limits, or what the output contains. For a mutation tool with 6 parameters, this is inadequate 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 extremely concise—a single sentence with no wasted words. It's front-loaded with the core action and resource. While under-specified, it's structurally efficient with every word contributing to the purpose statement.
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 this is a mutation tool with 6 parameters (1 required), 0% schema coverage, no annotations, but with an output schema, the description is insufficient. It doesn't explain what properties can be updated, what the 'pk' represents, or provide any behavioral context. The output schema helps with return values, but the description should do more for a complex update operation.
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 0%, meaning none of the 6 parameters have descriptions in the schema. The tool description provides no information about any parameters—not even the required 'pk' or what properties can be updated. This fails to compensate for the complete lack of schema documentation.
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 'Update a chart's properties' clearly states the verb (update) and resource (chart), but it's vague about what specific properties are involved and doesn't differentiate from sibling tools like update_dashboard or update_dataset. It provides a basic purpose but lacks specificity.
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 offers no guidance on when to use this tool versus alternatives like create_chart, delete_chart, or get_chart. There's no mention of prerequisites, context, or exclusions, leaving the agent with no usage direction beyond the tool name.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing dashboard.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes | ||
| title | No | ||
| published | No | ||
| json_metadata | No | ||
| position_json | No |
| Name | Required | Description |
|---|---|---|
No output 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 states 'update' implies mutation but doesn't cover permissions, side effects, response format, or error handling. This is inadequate for a mutation tool with zero annotation coverage, leaving critical behavioral traits unspecified.
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 extremely concise with a single sentence ('Update an existing dashboard.'), which is front-loaded and wastes no words. However, this conciseness comes at the cost of under-specification, but based on the dimension's focus on brevity and structure, it scores highly.
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 (mutation with 5 parameters, 0% schema coverage, no annotations) and the presence of an output schema, the description is incomplete. It doesn't explain parameters, usage context, or behavioral details, relying too heavily on the output schema without providing necessary upfront context for effective tool selection.
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 0%, so the description must compensate by explaining parameters. It mentions no parameters at all, failing to clarify the meaning of 'pk', 'title', 'published', 'json_metadata', or 'position_json'. This leaves all 5 parameters undocumented, significantly below the baseline expectation.
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 'Update an existing dashboard' clearly states the verb ('update') and resource ('dashboard'), but it's vague about what specific aspects are updated. It doesn't differentiate from sibling tools like 'update_chart' or 'update_dataset' beyond the resource name, and it lacks specificity about the update scope.
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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a dashboard PK), exclusions, or comparisons with siblings like 'publish_dashboard' or 'copy_dashboard'. The description offers no contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a dataset's properties.
| Name | Required | Description | Default |
|---|---|---|---|
| pk | Yes | ||
| table_name | No | ||
| description | No | ||
| sql | No | ||
| schema | No | ||
| cache_timeout | No | ||
| is_managed_externally | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'update' implies mutation, but doesn't disclose permissions required, whether changes are reversible, rate limits, or what the output contains. This is a significant gap for a mutation tool with zero annotation coverage.
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 a single, efficient sentence with no wasted words. It's appropriately sized and front-loaded, making it easy to parse quickly, though this conciseness comes at the cost of detail.
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, mutation operation) and the presence of an output schema, the description is incomplete. It lacks parameter explanations, behavioral context, and usage guidelines, but the output schema mitigates some gaps by documenting return values, making it minimally 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 description coverage is 0%, so the description must compensate for undocumented parameters. It mentions 'properties' generally but doesn't list or explain any of the 7 parameters (e.g., 'pk', 'table_name', 'description'), failing to add meaningful semantics beyond the bare 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 'Update a dataset's properties' clearly states the verb ('update') and resource ('dataset'), but it's vague about which specific properties can be updated. It doesn't distinguish from sibling tools like 'update_chart' or 'update_dashboard' beyond the resource type, and lacks specificity about the scope of 'properties'.
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?
No guidance is provided on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a dataset 'pk'), when not to use it, or how it differs from related tools like 'create_dataset' or 'refresh_dataset', leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0copy_dashboardcreate_chartcreate_dashboardcreate_datasetdelete_chartdelete_dashboarddelete_datasetestimate_query_costexecute_sqlformat_sqlget_chartget_chart_dataget_dashboardget_dashboard_chartsget_dashboard_datasetsget_databaseget_datasetget_dataset_related_objectsget_or_create_datasetget_select_starget_table_metadatalist_chartslist_dashboardslist_databaseslist_datasetslist_saved_querieslist_schemaslist_tablespublish_dashboardrefresh_datasetsave_queryupdate_chartupdate_dashboardupdate_datasetScored across 34 tools
Every tool has a clearly distinct purpose targeting specific resources (charts, dashboards, datasets, databases, queries) and actions (create, get, list, update, delete, execute, format, etc.), with no apparent overlap or ambiguity. For example, get_chart, get_chart_data, and list_charts serve different functions without confusion.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_chart, delete_dashboard, list_datasets, and update_dataset, with no deviations in style or convention. This predictability makes the tool set easy to navigate and understand.
With 34 tools, the count is borderline high for typical MCP server scopes, which often range from 3-15 tools. While it covers a comprehensive Superset domain, it may feel heavy and potentially overwhelming for agents, though not extreme like 50+ tools.
The tool surface provides complete CRUD/lifecycle coverage for charts, dashboards, datasets, and queries, along with execution, formatting, and metadata operations. There are no obvious gaps; agents can perform all core workflows from creation to deletion and analysis without dead ends.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Draxlr's remote MCP server connects AI assistants to your SQL databases and dashboards. Explore schemas, run read-only queries, manage saved queries and dashboards, and export results, all with row-level security so each user sees only their own data.
