Analítica local-primero y gobernada para clientes MCP sobre SQLite y PostgreSQL.
mcp-data-analysis-agent proporciona a un cliente MCP una pequeña capa de acceso a datos auditable en lugar de acceso directo a la base de datos. Valida SQL antes de la ejecución, utiliza conexiones de solo lectura, limita los resultados y el tiempo de ejecución, escribe registros de observabilidad respaldados por recibos y mantiene las credenciales en la máquina del operador.
Los clientes MCP pueden razonar sobre datos, pero no deberían recibir credenciales de base de datos sin restricciones ni ejecutar silenciosamente declaraciones arbitrarias. Este proyecto proporciona un punto de control local para ese límite:
Mantener rutas de base de datos, URLs, contraseñas y tokens en un archivo .env ignorado.
Permitir solo una declaración SELECT o WITH parametrizada.
Bloquear mutaciones, DDL, comandos, adjuntos, múltiples declaraciones, funciones inseguras, campos restringidos y rutas de artefactos inseguras.
Requerir acceso de solo lectura a nivel de base de datos además de la política de la aplicación.
Preservar SQL normalizado, tiempos, vinculación de tareas, recibos, hashes y líneas de tiempo de eventos para auditoría posterior.
El servidor usa solo stdio. No aloja una API pública, no sube datos fuente, no almacena credenciales remotas ni crea usuarios de base de datos de producción.
Related MCP server: sql-explorer-mcp
Acceso a SQLite y PostgreSQL a través de SQLAlchemy Core con validación de política SQLGlot.
Descubrimiento de fuente, esquema, relaciones, perfil, calidad/frescura y deriva de esquema.
Validación, planes de explicación, ejecución acotada, paginación con desplazamiento no negativo, cancelación, tiempos de espera y límites de concurrencia.
Clasificaciones para campos/fuentes públicos, internos, confidenciales y restringidos.
Métricas semánticas aprobadas, recetas nativas de Git, comparación de períodos, detección de cambios y recomendaciones de gráficos.
Paneles HTML sin conexión, CSV, Parquet, PDF Typst, metadatos de recibos y directorios de salida atómicos seguros.
Carga de contexto ClineFlow, diarios de tareas, registros de consultas/ejecuciones inmutables, líneas de tiempo de eventos y verificación de integridad.
Fixtures deterministas de retail, SaaS y soporte, incluidos fixtures de paridad local SQLite-a-PostgreSQL.
Python 3.11 o más reciente y uv.
Typst para la instalación de renderizado de informes compatible.
Herramientas de línea de comandos de PostgreSQL, incluido createdb para fixtures de paridad locales.
Un bundle ClineFlow/OKF saludable en el proyecto objetivo.
Ejecute mcp-data-cli preflight para instalar o informar sobre las herramientas locales requeridas a través de un administrador de paquetes de ámbito de usuario disponible. Nunca contacta con una fuente configurada. mcp-data-cli doctor valida la instalación local; ninguna fuente configurada se informa como configuration_pending, no como un fallo de instalación.
Cuando se le pida a un agente u operador que instale este repositorio de GitHub en un proyecto, use el instalador de repositorio—no un comando uv tool install simple:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bashEl instalador instala la herramienta de línea de comandos e inicializa el directorio desde el que se ejecutó. Crea el playground de retail determinista ignorado, escribe el único valor privado MCP_DATA_SOURCE_URL en .env, escribe la política de fuente y fusiona el servidor MCP en cada cliente compatible detectado. No copia el paquete en el proyecto y nunca pone una URL de base de datos o credencial en una configuración de cliente. Los avisos de habilitación/confianza del cliente y reinicio permanecen bajo el control de cada aplicación cliente.
uv tool install instala intencionalmente ejecutables a nivel de usuario y no ejecuta ganchos post-instalación que muten el proyecto. Úselo solo cuando quiera instalar el ejecutable por separado, luego ejecute mcp-data-cli init usted mismo.
uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctorPara instalar la versión actual del repositorio antes de un lanzamiento de paquete, reemplace el comando de instalación con:
uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.gitEn el primer uso del servidor en cualquier cliente MCP compatible, el agente crea y abre un playground SQLite de retail determinista solo para desarrollo en .mcp-data/playground.sqlite. La herramienta MCP compartida welcome explica cómo explorarlo y cómo cambiar a una fuente real. init materializa el mismo playground en la política de proyecto explícita y en el .env privado, luego fusiona entradas de cliente MCP seguras después de una confirmación. El instalador de repositorio explícito usa init --yes porque ejecutar ese instalador es la única autorización para esas escrituras con ámbito.
Use setup --all para previsualizar solo la configuración del cliente, o setup --all --apply para fusionar solo la entrada stdio mcp-data-analysis después de una confirmación explícita. Preserva servidores y configuraciones no relacionados. Use setup --status para inspeccionar la detección y el estado de configuración actual.
Cliente | Ámbito preferido | Respaldo | Acción del operador después de setup |
Claude Code |
| Configuración de usuario | Revise la aprobación del servidor del proyecto cuando se le solicite. |
VS Code / GitHub Copilot |
| Configuración MCP de usuario | Reinicie o use la gestión de servidores MCP; confíe en el servidor. |
Cline, Cursor, Windsurf | Configuración MCP del proyecto | Configuración de usuario del cliente | Reinicie o recargue el cliente y apruebe/confíe en el servidor. |
Continue | Fragmento | Configuración de usuario | Reinicie Continue y use el modo Agente. |
Codex | — |
| Reinicie Codex; este es el respaldo de ámbito de usuario estrecho. |
Setup configura solo definiciones MCP. No puede omitir el aviso de confianza/habilitación de un cliente ni lanzar/reiniciar un IDE. Los detalles de configuración de VS Code están documentados por VS Code y GitHub Copilot en VS Code; Continue documenta fragmentos MCP de proyecto en su guía MCP.
Para un wheel versionado y su checksum SHA-256 publicado:
MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.shEl bootstrap requiere curl y uv, verifica el artefacto con sha256sum o shasum, e instala solo después de que el checksum coincida. Luego inicializa el proyecto actual exactamente como lo hace el instalador de repositorio. No usa sudo ni contacta con una base de datos de producción; crea solo datos de demostración deterministas locales.
La instalación estándar usa exactamente una fuente activa, llamada data, y exactamente un valor privado en .env: MCP_DATA_SOURCE_URL. No es una constante de paquete ni un valor de prueba—es el único valor que el operador cambia para apuntar a su propia base de datos de solo lectura. Mantenga .env privado; está ignorado por Git.
En el primer uso, data apunta automáticamente al playground de retail generado. Ejecute mcp-data-cli init cuando esté listo para materializar esa elección en el .env del proyecto; escribe:
MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'El playground son datos sintéticos solo para desarrollo. Permite que una nueva instalación ejecute descubrimiento de esquema, consultas gobernadas, recibos e informes inmediatamente; nunca son datos de producción y nunca se sobrescriben con una ejecución posterior de init. Todos los clientes compatibles reciben las mismas instrucciones de bienvenida del servidor stdio y la herramienta MCP welcome.
# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30
# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"
[classification.columns]
email = "restricted"# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'Para SQLite, haga que la misma variable única sea una ruta de archivo absoluta o una URL SQLite. Para PostgreSQL, use una URL postgres:// o postgresql://. No se necesita configuración manual de dialecto:
MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'Use data como argumento de fuente en llamadas CLI, por ejemplo mcp-data-cli schema data. El agente rechaza esquemas de URL no compatibles, rutas SQLite relativas y un dialecto declarado heredado que entre en conflicto con la URL. Las políticas multi-fuente establecidas siguen siendo legibles, pero init se niega deliberadamente a reescribirlas; migre manualmente o comience un nuevo proyecto simplificado.
Para PostgreSQL, use una cuenta dedicada de privilegios mínimos sin privilegios de escritura o DDL. El agente también habilita una sesión de solo lectura y aplica la ruta de búsqueda de esquema configurada, pero el control de acceso del lado de la base de datos sigue siendo obligatorio.
Valide antes de ejecutar, luego inspeccione el plan y ejecute una consulta acotada:
mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0Cree una tarea explícita cuando varias operaciones pertenezcan a un análisis:
mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>Genere informes en un directorio nuevo seleccionado por el llamador. Se rechazan directorios existentes y el recorrido de enlaces simbólicos.
mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquetCada informe contiene HTML sin conexión, CSV, artefactos opcionales Parquet/PDF, metadatos de recibos, rutas y hashes de contenido. Los artefactos generados, fuentes y credenciales no deben ser confirmados.
init crea solo el pequeño playground de retail descrito anteriormente. Los contribuyentes pueden generar fixtures sintéticos deterministas adicionales explícitamente:
mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
mcp-data-cli seed-postgres retail --seed 1dataset-postgres usa createdb local, rechaza un nombre de base de datos existente, crea datos SQLite solo en un directorio temporal, luego los copia a la nueva base de datos PostgreSQL bajo el esquema mcp_parity. No requiere una URL PostgreSQL desechable proporcionada manualmente.
seed-postgres es para una base de datos de prueba aislada ya aprovisionada. Lee la URL de prueba privada del entorno y reemplaza solo sus esquemas reservados mcp_seed_retail, mcp_seed_saas o mcp_seed_support. Nunca toca esquemas públicos/de aplicación.
Ejecute la suite de calidad local completa con una instancia PostgreSQL aislada al desarrollar el comportamiento del adaptador. CI cubre linting, tipado, pruebas, puertas de cobertura, renderizado real de Typst, paridad SQLite/PostgreSQL, escaneo de secretos, auditoría de dependencias, generación de SBOM y automatización de lanzamiento de publicación confiable.
uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okfLos módulos de configuración crítica de seguridad, contexto, libro mayor y política SQL requieren 100% de cobertura de líneas y ramas. Las puertas generales requieren al menos 90% de cobertura de líneas y 85% de cobertura de ramas.
Las consultas deben estar parametrizadas y se validan antes de la conexión/ejecución de la base de datos.
Los límites de resultados y desplazamientos están gobernados por la política del proyecto; el SQL del llamador no puede omitirlos.
Las columnas restringidas se rechazan antes de la ejecución y los parámetros similares a secretos se redactan en los registros de observabilidad.
Los diarios de tareas, recibos de consultas, ejecuciones y eventos se almacenan bajo knowledge/ y observability/; las URLs de base de datos, secretos sin procesar, bases de datos fuente, cachés de resultados y binarios de informes están excluidos.
Los conjuntos de datos sintéticos locales son solo infraestructura de desarrollo y no son incorporación de producción.
Consulte guía de operaciones, la política de seguridad y la licencia MIT para el contrato completo de operación y divulgación.
Use commits enfocados y preserve las etiquetas anotadas checkpoint-*: son puntos de reversión explícitos para hitos de entrega. Actualice el diario de ingeniería ClineFlow activo y el registro de conocimiento con cambios materiales, ejecute la validación OKF, luego confirme la implementación y la evidencia de conocimiento juntas.
GitHub Actions construye y verifica distribuciones en la publicación del lanzamiento. Los endpoints de lanzamiento y las credenciales de publicación son configuración del repositorio; nunca se almacenan en este código.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| objective | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| task_id | No | ||
| source_alias | Yes | ||
| current_parameters_json | Yes | ||
| previous_parameters_json | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | ||
| findings | Yes | ||
| next_steps | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a seeded retail demo only after the user explicitly approves it.
| Name | Required | Description | Default |
|---|---|---|---|
| confirmed | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of revealing behavior. It discloses that the action creates a demo and requires approval, but it does not mention potential side effects such as overwriting data, resource usage, or reversibility.
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?
One concise sentence that communicates both the action and the required precondition. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple boolean-parameter tool, the description provides sufficient context for when and how to call it. It does not describe the output, but given the low complexity and presence of an output schema, this is not a significant gap.
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 strongly implies that the boolean 'confirmed' parameter should be true only after explicit user approval, giving meaning to an otherwise undocumented parameter. This adequately compensates for the lack of schema-level 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?
Clearly states the action — create a seeded retail demo — and includes the critical precondition of explicit user approval. This distinguishes it from the many sibling tools by specifying a concrete resource and operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs that the tool should only be used after user approval, providing a clear trigger condition. It does not name alternatives, but the condition is strong enough to guide appropriate invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| task_id | No | ||
| source_alias | Yes | ||
| current_parameters_json | Yes | ||
| baseline_parameters_json | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| source_alias | Yes | ||
| parameters_json | No | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| source_alias | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Validate this project's source configuration without revealing its URL.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full responsibility. It discloses the validation behavior and explicitly guarantees URL non-disclosure. It does not mention side effects (e.g., whether it modifies configuration), but the term 'preflight' suggests read-only validation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant words. It delivers the core purpose and a key constraint 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 absence of parameters and the simple nature of the tool, the description provides sufficient context. It explains what the tool does and highlights a critical behavioral guarantee; no additional information is needed for basic 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?
The input schema has zero properties, so there are no parameters to describe. The baseline score of 4 is applied, and the description adds no parameter-specific meaning because none exists.
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 function: validating the project's source configuration. It also specifies a distinctive constraint (without revealing its URL), which distinguishes it from sibling tools like validate_and_execute or explain_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 implies appropriate usage by highlighting the privacy aspect ('without revealing its URL'), suggesting this tool is preferred when URL confidentiality is required. However, it does not explicitly name alternative tools or state when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | ||
| task_id | No |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| source_alias | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| source_alias | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| limit | No | ||
| offset | No | ||
| task_id | No | ||
| source_alias | Yes | ||
| parameters_json | No | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
| sql | Yes | ||
| source_alias | Yes | ||
| parameters_json | No | {} |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Tool has no description.
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?
Tool has no 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?
Tool has no description.
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?
Tool has no description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Tool has no description.
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?
Tool has no description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain the project source-file configuration requirement.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full burden. 'Explain' implies a read-only, non-destructive action, but the description does not explicitly state that it makes no changes, takes no input, or what kind of output it returns.
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, focused sentence with no redundant or extraneous content. It is concise 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?
The description conveys the basic action but omits contextual details such as what the explanation will contain, whether it returns text or data, and how it relates to the other tools in the environment. It is adequate for a simple welcome/help tool but not 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?
The input schema is an empty object and the schema coverage is complete, so there are no parameters to document. The description does not need to elaborate on inputs because none exist.
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 a specific action—'Explain'—and identifies the resource/topic as 'the project source-file configuration requirement.' It is distinct from the sibling tools, though it does not elaborate on what that requirement entails.
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 gives no guidance on when to use this tool versus any alternative, nor does it mention prerequisites or context. A user must infer its purpose from the brief sentence 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.0begin_analysis_taskcancel_analysis_taskcompare_periodscomplete_analysis_taskconfigure_demodetect_changeevaluate_analysis_taskexplain_sqlget_schemalist_recipeslist_sourcespreflightrun_metricschema_statesuggest_joinstask_timelinevalidate_and_executevalidate_sqlverify_observabilitywelcomeScored across 20 tools
Many tools have clear distinct responsibilities, but some pairs overlap in intent (get_schema vs schema_state, validate_sql vs validate_and_execute) and task lifecycle tools (begin/complete/evaluate) could be confused without descriptions. The boundaries are mostly inferable but not consistently crisp.
Tool names mix verb-first actions (verify_observability, get_schema, run_metric) with noun-only states (schema_state, task_timeline) and one-word commands (preflight, welcome). The pattern is inconsistent, though most names are readable.
20 tools is on the higher side but not unreasonable for a data-analysis agent covering tasks, schema, SQL, metrics, and recipes. Several tools could be consolidated (e.g., schema_state into get_schema, validate_and_execute with validate_sql), which would make the count more focused.
The set covers core data-analysis workflows: task lifecycle, schema introspection, SQL validation, metric execution, comparisons, and change detection. It lacks explicit data fetching/result retrieval endpoints, but the metric and SQL tools likely fill that role; onboarding tools are extra rather than essential.
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Query, join, profile, clean and convert CSV/JSON/Parquet with server-side DuckDB over MCP.
MCP server for interacting with the Supabase platform
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
