The SuperDB MCP Server enables AI assistants to interact with SuperDB by executing SuperSQL queries, managing databases, accessing documentation, and leveraging optional LSP-powered code assistance.
Query Execution: Run SuperSQL queries on data files or inline data (super_query) or database pools (super_db_query), with output in JSON, SUP, CSV, or table formats
Query Validation: Check SuperSQL syntax without executing, with diagnostics and migration hints for zq-to-SuperDB changes (super_validate)
Schema Inspection: Analyze data files to discover unique record shapes with counts and examples (super_schema)
Database Management: List pools, create new pools, and load data into a SuperDB lake (super_db_list, super_db_create_pool, super_db_load)
Documentation & Reference: Access expert syntax guides, upgrade/migration docs, grok patterns, and recipe functions (super_help, super_grok_patterns, super_recipes)
Environment Diagnostics: Get version info, environment configuration, LSP availability, and optionally compare two super binaries (super_info, super_lsp_status)
Cross-Version Compatibility Testing: Run queries against multiple SuperDB versions to detect breaking changes (super_test_compat)
LSP-Powered Code Assistance (requires optional SuperDB LSP): Get autocompletions at a cursor position (super_complete) and inline symbol documentation (super_docs)
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., "@SuperDB MCP Server show me the schema of my users.csv file"
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.
An MCP (Model Context Protocol) server for SuperDB that enables AI assistants to better compose SuperSQL queries, optionally backed by an LSP.
Related MCP server: DuckDB MCP Server
SuperDB is the successor to zq from Brim Data. LLMs have limited knowledge of its syntax, so this MCP server provides the context AI assistants need to write correct queries.
# Install for current project only
claude mcp add superdb -- npx -y superdb-mcp@latest
# Install for all projects (user scope)
claude mcp add --scope user superdb -- npx -y superdb-mcp@latestUsing @latest auto-upgrades the MCP server on each Claude launch. To pin a
specific version, replace @latest with a version number (e.g., @0.1.0).
Add to your Claude Code settings (~/.claude/settings.json) or project .mcp.json:
{
"mcpServers": {
"superdb": {
"command": "npx",
"args": ["-y", "superdb-mcp@latest"]
}
}
}Or install globally:
npm install -g superdb-mcp{
"mcpServers": {
"superdb": {
"command": "superdb-mcp"
}
}
}git clone https://github.com/chrismo/superdb-mcp.git
cd superdb-mcp
npm install
npm run build{
"mcpServers": {
"superdb": {
"command": "node",
"args": ["/path/to/superdb-mcp/dist/index.js"]
}
}
}Only super_complete and super_docs use the LSP — query execution,
documentation, grok patterns, recipes, and database tools are fully
functional on their own. The
SuperDB LSP adds code completions
and symbol documentation for those who want it. Download a binary from the
releases page, then
point the MCP server to it:
export SUPERDB_LSP_PATH=/path/to/superdb-lspAdd the export to your shell profile for persistence. Run super_lsp_status
to verify setup.
super_queryExecute a SuperSQL query on data files. On errors, includes migration hints for common zq-to-SuperDB syntax changes (yield→values, over→unnest, func→fn, etc.).
query: string # Required: The SuperSQL query
files?: string[] # Pipeline-style input (not for SQL FROM; use absolute paths in FROM)
data?: string # Inline data (alternative to files)
format?: string # Output: json (default), sup, csv, table, line, tsv, jsup, zeek
inputFormat?: string # Force input formatBinary formats (bsup, csup, db, parquet, arrows) are rejected: results
are returned as text, and binary output does not survive UTF-8 decoding. Use
line for undecorated scalar output.
super_schemaInspect types in a data file by finding unique shapes with counts and examples.
file: string # Path to data filesuper_db_queryQuery data from a database pool.
query: string # The SuperSQL query
pool?: string # Pool name
lake?: string # Lake path
format?: string # Output: json (default), sup, csv, table, line, tsv, jsup, zeeksuper_db_listList all pools in a SuperDB database.
lake?: string # Lake path (default: ~/.super)super_db_create_poolCreate a new pool.
name: string # Pool name
orderBy?: string # Sort key
lake?: string # Lake pathsuper_db_loadLoad data into a pool.
pool: string # Pool name
files?: string[] # Files to load
data?: string # Inline data
lake?: string # Lake pathContent targets SuperDB v0.1.0. Responses include a version_note when
the installed runtime differs from the content target.
super_helpGet SuperDB documentation — expert guide, migration docs, or tutorials.
topic: string # "expert", "upgrade", "tutorials", or "tutorial:<name>"super_grok_patternsSearch/filter 89 grok patterns for parsing logs, timestamps, IPs, and more.
query?: string # Filter by pattern name or regex contentsuper_recipesSearch/list 16 recipe functions (from superkit) with signatures, descriptions, and examples.
query?: string # Filter by function name, description, or source filesuper_infoGet SuperDB version info, environment configuration, LSP availability, and installation instructions.
compare_to?: string # Optional path to another super binary to comparesuper_lsp_statusCheck if the SuperDB LSP is installed and get installation instructions if not.
# No parameterssuper_test_compatTest a query against multiple SuperDB versions to detect breaking changes.
query: string # The query to test
versions: string[] # Paths to different super binariesRequire SUPERDB_LSP_PATH environment variable to be set.
super_completeGet code completions for a SuperSQL query at a cursor position.
query: string # The query text
line: number # Line number (0-based)
character: number # Character offset (0-based)super_docsGet documentation for a symbol at a position in a query.
query: string # The query text
line: number # Line number (0-based)
character: number # Character offset (0-based)With the MCP server configured, Claude can execute queries like:
super_query({
query: "where status == 'active' | aggregate count() by category",
files: ["data.json"]
})No shell escaping needed - the query string is passed directly.
Node.js 18+
super binary in PATH:
Homebrew (official, latest build)
asdf-superdb (community, versioned builds)
This MCP server uses its own independent semver, decoupled from SuperDB's
version. Query tools (super_query, super_schema, etc.) work with any
version of the super binary, so the MCP server is useful even if your
runtime is older or newer than the target. Bundled content — documentation,
tutorials, grok patterns, and recipes — is written for a specific SuperDB
release, so aligning your runtime with the target version gives the best
results. The super_info tool reports both versions, and content tools
include a version_note when they differ.
The optional SuperDB LSP enables code completions and documentation lookup — see installation instructions.
MCP Version | SuperDB Target | Notes |
1.1.0 | v0.1.0 | Grok patterns, tutorials, recipes from superkit |
1.0.0 | v0.1.0 | Switched to independent semver |
0.1.0 | v0.1.0 | Aligned with first official SuperDB release |
0.51231.x | 0.51231 (pre-release) | Legacy pseudo-version scheme |
This MCP server is licensed under the BSD-3-Clause License.
This project wraps SuperDB, which is
licensed under the
SuperDB Source Available License.
The MCP server does not distribute SuperDB source code or binaries; it invokes
a locally installed super binary at runtime.
Get code completions for a SuperSQL query at a position. Requires SUPERDB_LSP_PATH to be set.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query text | |
| line | Yes | Line number (0-based) | |
| character | Yes | Character offset (0-based) |
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 an environmental requirement (SUPERDB_LSP_PATH), which adds some context, but it doesn't describe what the tool returns (e.g., completion items, error messages), whether it's read-only or has side effects, or any rate limits. For a tool with no annotations, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose and followed by a prerequisite. There is no wasted text, and every sentence earns its place by providing essential information efficiently.
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 code completion tool with no annotations and no output schema, the description is incomplete. It lacks details on return values (e.g., what completions look like), error handling, or behavioral traits like whether it's a read operation. This makes it inadequate for an AI agent to fully understand how to use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, so the schema already documents all three parameters (query, line, character). The description doesn't add any additional meaning or examples beyond what the schema provides, such as explaining how line and character offsets work in practice. 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 action ('Get code completions') and resource ('for a SuperSQL query at a position'), making the purpose understandable. However, it doesn't explicitly differentiate from sibling tools like super_query or super_help, which might also involve query-related operations, so it's not a perfect 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 some context by mentioning the requirement for SUPERDB_LSP_PATH to be set, which implies when to use it (when that environment variable is configured). However, it doesn't specify when not to use it or name alternatives among siblings, such as super_help for general assistance or super_query for executing queries, leaving usage guidance implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new pool in a SuperDB database.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Name for the new pool | |
| orderBy | No | Field to order/sort data by | |
| lake | No | Lake path (default: uses SUPER_DB_LAKE env or ~/.super) |
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 'Create' which implies a write/mutation operation, but it doesn't cover permissions needed, whether the operation is idempotent, error handling, or what happens on success (e.g., returns a pool ID). This leaves significant gaps for a mutation 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 directly states the tool's purpose without any unnecessary words. It's front-loaded and efficiently communicates the core action, 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 that this is a mutation tool (creating a pool) with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like side effects, return values, or error conditions, which are critical for safe and effective use by 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?
The description adds no parameter semantics beyond what the input schema provides. Since schema description coverage is 100%, the baseline score is 3. The description doesn't explain how parameters interact (e.g., if 'orderBy' affects pool creation) or provide additional context, so it doesn't exceed 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 action ('Create') and resource ('new pool in a SuperDB database'), making the purpose immediately understandable. However, it doesn't differentiate this tool from potential sibling tools like 'super_db_load' or 'super_db_list', which might also involve pool operations, 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. With siblings like 'super_db_load' and 'super_db_list' that might relate to pools, there's no indication of prerequisites, context, or exclusions for using this creation tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all pools in a SuperDB database.
| Name | Required | Description | Default |
|---|---|---|---|
| lake | No | Lake path (default: uses SUPER_DB_LAKE env or ~/.super) |
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. While 'List' implies a read-only operation, it doesn't specify whether this requires authentication, has rate limits, returns paginated results, or what format the output takes. The description is minimal and lacks important 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 a single, efficient sentence that states exactly what the tool does with zero wasted words. It's appropriately sized for a simple list operation and gets straight to the point 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?
For a tool with no annotations and no output schema, the description is insufficiently complete. It doesn't explain what a 'pool' is in SuperDB context, what format the listing returns, or any operational constraints. Given the complexity implied by sibling tools and lack of structured metadata, more context would be 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 100%, so the schema already fully documents the single 'lake' parameter with its type and default behavior. The description adds no additional parameter information beyond what's in the schema, meeting 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 ('List') and resource ('all pools in a SuperDB database'), making the purpose immediately understandable. It doesn't explicitly differentiate from siblings like 'super_db_query' or 'super_db_load', but the verb 'List' suggests this is a read operation rather than querying or loading data.
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 'super_db_query' and 'super_db_load' that might also interact with pools, there's no indication of when listing pools is appropriate versus querying or loading them. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load data into a SuperDB database pool.
| Name | Required | Description | Default |
|---|---|---|---|
| pool | Yes | Pool name to load data into | |
| files | No | File paths to load | |
| data | No | Inline data to load (alternative to files) | |
| lake | No | Lake path (default: uses SUPER_DB_LAKE env or ~/.super) |
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 ('Load data') but doesn't describe what 'load' entails (e.g., overwrite, append, requires permissions), potential side effects, rate limits, or response format. 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 appropriately sized and front-loaded, directly stating the tool's purpose 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 this is a mutation tool (loading data) with no annotations and no output schema, the description is incomplete. It doesn't address behavioral aspects like permissions, side effects, or what happens on success/failure, which are critical for safe tool invocation in this context.
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 4 parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't clarify the relationship between 'files' and 'data' as alternatives). 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 verb ('Load') and resource ('data into a SuperDB database pool'), making the purpose understandable. However, it doesn't distinguish this tool from potential alternatives like 'super_db_create_pool' or 'super_db_query' that might also handle data operations, 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 'super_db_query' or 'super_db_create_pool'. It mentions no prerequisites, exclusions, or contextual cues for selection, leaving the agent with minimal usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query data from a SuperDB database pool.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query to execute | |
| pool | No | Pool name (can also use FROM in query) | |
| lake | No | Lake path (default: uses SUPER_DB_LAKE env or ~/.super) | |
| format | No | Output format (default: json) |
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 ('Query data') but doesn't mention critical aspects like whether this is read-only or has side effects, authentication requirements, rate limits, error handling, or what the response looks like. For a database query tool with zero annotation coverage, 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's appropriately sized and front-loaded, immediately conveying the core functionality 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 database query tool with no annotations and no output schema, the description is incomplete. It lacks information on behavioral traits, usage context, and output details, making it inadequate for an AI agent to fully understand how to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the input schema already documents all parameters thoroughly. The description adds no additional meaning beyond what's in the schema (e.g., it doesn't explain query syntax, pool selection nuances, or format implications). 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 verb ('Query') and resource ('data from a SuperDB database pool'), making the purpose immediately understandable. However, it doesn't differentiate this tool from sibling tools like 'super_query' or 'super_db_list', which likely have overlapping or related 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. With multiple sibling tools like 'super_query', 'super_db_list', and 'super_db_load', there's no indication of the specific scenarios, prerequisites, or exclusions for this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get documentation for a symbol at a position in a SuperSQL query. Requires SUPERDB_LSP_PATH to be set.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query text | |
| line | Yes | Line number (0-based) | |
| character | Yes | Character offset (0-based) |
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 an environment requirement ('SUPERDB_LSP_PATH'), which is useful context, but doesn't describe other behavioral traits such as whether this is a read-only operation, potential error conditions, rate limits, or what the output looks like (since there's no output schema). For a tool with no annotations, this leaves significant gaps in understanding its 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 extremely concise and front-loaded: it states the core purpose in the first part and adds a prerequisite in the second. Both sentences earn their place by providing essential information without any waste. It's appropriately sized for a tool with clear parameters and no complex behavior described.
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 (a tool for retrieving documentation based on query position) and the lack of annotations and output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., documentation text, error messages) or other contextual details like performance or limitations. The environment requirement is noted, but more information is needed for a tool that interacts with a query language and LSP.
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%, meaning the input schema already documents all parameters (query, line, character) with descriptions. The description doesn't add any additional meaning or context beyond what's in the schema, such as explaining how the position parameters interact or typical use cases. With high schema coverage, the baseline score is 3, as the description doesn't compensate but doesn't detract either.
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 documentation for a symbol at a position in a SuperSQL query.' It specifies the verb ('Get'), resource ('documentation'), and context ('SuperSQL query'), making it easy to understand what the tool does. However, it doesn't explicitly differentiate from sibling tools like 'super_help' or 'super_info', which might also provide documentation or information.
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 some usage context by stating 'Requires SUPERDB_LSP_PATH to be set,' which is a prerequisite. However, it doesn't offer guidance on when to use this tool versus alternatives like 'super_help' or 'super_info' (which might provide general help or info rather than symbol-specific documentation). The usage is implied but not explicitly compared to siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get SuperDB documentation. Call this before writing complex queries or when migrating from zq or earlier versions of SuperDB. Topics: expert (syntax guide), upgrade (zq migration).
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes | Documentation topic to retrieve |
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 describes what the tool does (retrieves documentation) and when to use it, but doesn't disclose important behavioral traits like whether this is a read-only operation, what format the documentation returns in, potential rate limits, or authentication requirements.
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 well-structured in just two sentences. The first sentence states the purpose, the second provides usage guidance and topic details. Every word earns its place with no wasted text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with no annotations and no output schema, the description provides adequate context about purpose and usage. However, it doesn't explain what format the documentation returns in or provide details about the differences between topic options, which would be helpful given the lack of output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'topic' fully documented with enum values. The description adds context about what topics are available ('expert (syntax guide), upgrade (zq migration)'), which provides semantic meaning beyond the schema's enum list, but doesn't explain the differences between the enum values.
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 SuperDB documentation' with specific use cases ('before writing complex queries or when migrating'). It distinguishes from some siblings like super_db_query or super_db_create_pool, but doesn't explicitly differentiate from super_docs which might have 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 clear context for when to use the tool ('before writing complex queries or when migrating'), including specific scenarios. However, it doesn't explicitly state when NOT to use it or name alternatives among the sibling tools, particularly super_docs which appears related.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get SuperDB version info, environment configuration, LSP availability, and installation instructions. Call this to check setup status or learn how to install the optional LSP for enhanced query assistance.
| Name | Required | Description | Default |
|---|---|---|---|
| compare_to | No | Optional path to another super binary to compare versions |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes what information is retrieved (version, config, LSP availability, instructions) and the tool's purpose (setup checks, installation learning). However, it lacks details on behavioral traits such as rate limits, authentication needs, or response format. The description adds value by explaining the tool's scope but doesn't fully compensate for the absence of annotations.
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 appropriately sized and front-loaded: the first sentence states the core functionality, and the second explains usage. Every sentence earns its place by providing essential information without redundancy. It's concise and well-structured for an agent to quickly grasp the tool's purpose and when to use it.
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 (1 optional parameter, no output schema, no annotations), the description is moderately complete. It covers the tool's purpose and usage but lacks details on output format or behavioral constraints. Without annotations or an output schema, the description should ideally provide more context on what to expect from the tool's response, but it's adequate for a simple informational 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 input schema has 1 parameter with 100% description coverage, so the schema already documents 'compare_to' as an optional path for version comparison. The description doesn't add any parameter-specific information beyond what the schema provides. Since schema coverage is high, the baseline score is 3, as the description doesn't enhance parameter understanding but doesn't need to given the comprehensive schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get SuperDB version info, environment configuration, LSP availability, and installation instructions.' It specifies the verb 'Get' and the resources (version info, config, LSP availability, instructions). However, it doesn't explicitly differentiate from sibling tools like 'super_lsp_status' or 'super_help', which might overlap in 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 clear usage context: 'Call this to check setup status or learn how to install the optional LSP for enhanced query assistance.' This indicates when to use the tool (for setup checks or installation guidance). It doesn't specify when not to use it or name alternatives among siblings, but the context is sufficiently clear for an agent to understand its primary use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check if the SuperDB LSP is installed and get installation instructions if not. The LSP enables code completions and documentation lookup for SuperSQL queries.
| Name | Required | Description | Default |
|---|---|---|---|
No 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 describes what the tool does (check installation status and provide instructions) and mentions the LSP's purpose (enabling code completions and documentation lookup). However, it doesn't disclose potential side effects, error conditions, or response format details that would be helpful for an agent.
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 perfectly concise with two sentences that each earn their place. The first sentence states the core functionality, while the second provides valuable context about why the LSP matters. There's no wasted language 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?
For a zero-parameter tool with no annotations and no output schema, the description provides adequate context about what the tool does and why. However, it doesn't describe what the output looks like (e.g., installation status indicators, instruction format) or potential error conditions, leaving some gaps for an agent trying to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters with 100% schema description coverage, so the baseline is 4. The description appropriately doesn't discuss parameters since none exist, focusing instead on the tool's purpose and context.
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 specific verbs ('check if installed', 'get installation instructions') and resources ('SuperDB LSP'). It distinguishes from siblings by focusing on LSP installation status rather than query execution, documentation lookup, or database 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 clear context about when to use this tool: when needing to verify LSP installation status or obtain installation instructions. It doesn't explicitly state when not to use it or name specific alternatives, but the context makes it clear this is for LSP setup rather than querying or documentation access.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute a SuperDB/SuperSQL query on data files. Returns structured results without shell escaping issues.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query to execute | |
| files | No | File paths to query (JSON, Parquet, CSV, SUP, etc.) | |
| data | No | Inline data to query (alternative to files) | |
| format | No | Output format (default: json) | |
| inputFormat | No | Force input format if auto-detection fails |
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 mentions the tool executes queries and returns structured results without shell escaping issues, but lacks details on error handling, performance implications, authentication needs, or rate limits. For a query tool with multiple parameters, 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 that front-loads the core purpose and key benefit. Every word earns its place, with no redundancy or unnecessary elaboration, 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 (5 parameters, no output schema, and no annotations), the description is incomplete. It fails to explain return values, error conditions, or behavioral traits like data source handling. For a query execution tool, more context on results and limitations 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 100%, so the schema fully documents all 5 parameters. The description adds minimal value by hinting at file types ('JSON, Parquet, CSV, SUP, etc.') and the 'inline data' alternative, but does not provide additional syntax, examples, or constraints beyond the schema. Baseline 3 is appropriate as 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 action ('Execute a SuperDB/SuperSQL query') and resource ('on data files'), with the specific benefit of 'Returns structured results without shell escaping issues.' It distinguishes from siblings like super_db_query by mentioning SuperDB/SuperSQL and file-based queries, though not explicitly contrasting with all alternatives.
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 siblings such as super_db_query or super_db_load, nor does it mention prerequisites like file accessibility or data formats. Usage is implied through the mention of 'data files' and 'inline data,' but no explicit when/when-not rules are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Inspect the schema/types of a data file by finding all unique shapes (record types) with counts and examples.
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the data file |
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 describes the action ('inspect') and output ('unique shapes with counts and examples'), but does not cover critical aspects like whether it's read-only, potential side effects, performance considerations, or error handling. For a tool with no annotations, this leaves significant gaps in understanding its 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, well-structured sentence that efficiently conveys the tool's purpose without unnecessary words. It is front-loaded with the core action and includes key details like 'unique shapes', 'counts', and 'examples', making it highly concise and effective.
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 (analyzing data file schemas), lack of annotations, and no output schema, the description is minimally adequate. It explains what the tool does but does not address behavioral traits, usage context, or output details. This leaves the agent with incomplete information, especially for a tool that might involve data processing nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'file' documented as 'Path to the data file'. The description adds no additional parameter semantics beyond this, such as file format expectations or constraints. Given the high schema coverage, a baseline score of 3 is appropriate, as the schema adequately handles parameter 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: 'Inspect the schema/types of a data file by finding all unique shapes (record types) with counts and examples.' It specifies the verb ('inspect'), resource ('schema/types of a data file'), and method ('finding all unique shapes with counts and examples'). However, it does not explicitly differentiate from sibling tools like 'super_validate' or 'super_query', which might have overlapping functionality, keeping 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 does not mention prerequisites, exclusions, or compare it to siblings such as 'super_validate' or 'super_query', which could be relevant for schema-related tasks. This lack of contextual direction leaves the agent with minimal usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Test a query against multiple SuperDB versions to detect syntax breaking changes. Useful for migration testing.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query to test | |
| versions | Yes | Paths to different super binaries to test against |
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 tool tests queries against multiple versions to detect breaking changes, but doesn't describe how it behaves—e.g., whether it runs queries sequentially or in parallel, what output format to expect, error handling, or performance implications. This leaves significant gaps in understanding the tool's 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 highly concise and front-loaded, consisting of two sentences that directly convey the tool's purpose and usage context. Every sentence earns its place without redundancy, making it 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 complexity (testing queries across versions) and lack of annotations or output schema, the description is incomplete. It doesn't explain what the tool returns (e.g., success/failure indicators, error details per version), behavioral traits, or integration with sibling tools. While concise, it falls short of providing enough context 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?
The input schema has 100% description coverage, with clear documentation for both parameters ('query' and 'versions'). The description adds minimal value beyond the schema, as it doesn't provide additional context like example queries, version format details, or constraints. Baseline 3 is appropriate since the schema already 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: 'Test a query against multiple SuperDB versions to detect syntax breaking changes.' It specifies the verb ('test'), resource ('query'), and objective ('detect syntax breaking changes'). However, it doesn't explicitly differentiate from siblings like 'super_query' or 'super_validate', which might have 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 implied usage context with 'Useful for migration testing,' suggesting when to use this tool. However, it lacks explicit guidance on when to choose this over alternatives like 'super_query' (for single-version queries) or 'super_validate' (for validation without version testing), and doesn't mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate SuperSQL query syntax without executing. Returns diagnostics with position info and migration suggestions for common zq-to-SuperDB errors.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The SuperSQL query to validate |
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 effectively describes key traits: it's a non-executing validation tool (implying read-only and non-destructive), returns diagnostics with position information, and offers migration suggestions for specific error types. It does not mention rate limits, authentication needs, or detailed output format, but covers essential behavior adequately for a validation 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 appropriately sized and front-loaded, consisting of a single, efficient sentence that conveys the core purpose, behavior, and output. Every word earns its place, with no redundant information or fluff, making it easy for an AI agent to parse and understand 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 complexity (a validation tool with one parameter), no annotations, and no output schema, the description is mostly complete. It explains what the tool does, its non-executing nature, and the type of output (diagnostics with position info and migration suggestions). However, it lacks details on the exact format of the diagnostics or error types, which could be helpful for an agent to interpret results, preventing a perfect score.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'query' documented as 'The SuperSQL query to validate'. The description adds no additional parameter semantics beyond this, such as query length limits or syntax examples. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description does not compensate but also does not 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 clearly states the tool's purpose with specific verbs ('validate SuperSQL query syntax without executing') and distinguishes it from siblings like super_query (which likely executes queries) and super_test_compat (which might test compatibility). It explicitly mentions what it does not do (execute) and what it returns (diagnostics with position info and migration suggestions).
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 clear context for when to use this tool: for syntax validation and migration error checking, particularly for converting from 'zq' to SuperDB. However, it does not explicitly state when not to use it or name specific alternatives among the siblings (e.g., super_query for execution, super_test_compat for compatibility testing), which prevents a perfect score.
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.51231.6super_completesuper_db_create_poolsuper_db_listsuper_db_loadsuper_db_querysuper_docssuper_helpsuper_infosuper_lsp_statussuper_querysuper_schemasuper_test_compatsuper_validateScored across 13 tools
Most tools have distinct purposes, such as super_db_create_pool for pool creation and super_query for query execution, but there is some overlap between super_query and super_db_query (both involve querying data) and between super_docs and super_help (both provide documentation). The descriptions help clarify differences, but minor confusion could occur.
All tool names follow a consistent snake_case pattern with a 'super_' prefix, such as super_db_create_pool and super_validate. This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style.
With 13 tools, the count is well-scoped for a database server covering setup, querying, validation, and documentation. Each tool serves a specific function, such as super_info for setup checks and super_test_compat for migration testing, ensuring no redundancy or gaps in the core operations.
The tool set provides comprehensive coverage for SuperDB operations, including pool management (create, list, load), querying (query, validate), and setup assistance (info, lsp_status). Minor gaps exist, such as no explicit tools for updating or deleting pools, but core workflows like query execution and migration are well-supported.
Explore, query, and inspect SQLite databases with ease. List tables, preview results, and view det…
Your Supabase account in natural language: run SQL, apply migrations, manage tables, storage, edge f
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
