Lokal zuerst, kontrollierte Analytik für MCP-Clients über SQLite und PostgreSQL.
mcp-data-analysis-agent gibt einem MCP-Client eine kleine, prüfbare Datenzugriffsschicht statt direktem Datenbankzugriff. Es validiert SQL vor der Ausführung, verwendet schreibgeschützte Verbindungen, begrenzt Ergebnisse und Ausführungszeit, schreibt belegbasierte Beobachtbarkeitsdatensätze und hält Anmeldedaten auf dem Rechner des Betreibers.
MCP-Clients können über Daten nachdenken, sollten aber keine uneingeschränkten Datenbankanmeldedaten erhalten oder stillschweigend beliebige Anweisungen ausführen. Dieses Projekt bietet einen lokalen Kontrollpunkt für diese Grenze:
Datenbankpfade, URLs, Passwörter und Token in einer ignorierten .env-Datei aufbewahren.
Nur eine einzelne parametrisierte SELECT- oder WITH-Anweisung zulassen.
Mutationen, DDL, Befehle, Anhänge, Mehrfachanweisungen, unsichere Funktionen, eingeschränkte Felder und unsichere Artefaktpfade blockieren.
Zusätzlich zur Anwendungspolicy schreibgeschützten Datenbankzugriff auf Datenbankebene verlangen.
Normalisiertes SQL, Zeitmessung, Aufgabenverknüpfung, Belege, Hashes und Ereigniszeitlinien für spätere Prüfung aufbewahren.
Der Server verwendet nur stdio. Er hostet keine öffentliche API, lädt keine Quelldaten hoch, speichert keine entfernten Anmeldedaten und erstellt keine Produktionsdatenbankbenutzer.
Related MCP server: sql-explorer-mcp
SQLite- und PostgreSQL-Zugriff über SQLAlchemy Core mit SQLGlot-Policy-Validierung.
Quellen-, Schema-, Beziehungs-, Profil-, Qualitäts-/Frische- und Schema-Drift-Erkennung.
Validierung, Erklärungspläne, begrenzte Ausführung, nicht-negative Offset-Paginierung, Abbruch, Zeitüberschreitungen und Nebenläufigkeitsgrenzen.
Klassifizierungen für öffentliche, interne, vertrauliche und eingeschränkte Felder/Quellen.
Genehmigte semantische Metriken, Git-native Rezepte, Periodenvergleich, Änderungserkennung und Diagrammempfehlungen.
Offline-HTML-Dashboards, CSV, Parquet, Typst-PDF, Belegmetadaten und sichere atomare Ausgabeverzeichnisse.
ClineFlow-Kontextladung, Aufgabenjournale, unveränderliche Abfrage-/Ausführungsdatensätze, Ereigniszeitlinien und Integritätsprüfung.
Deterministische Retail-, SaaS- und Support-Fixtures, einschließlich lokaler SQLite-zu-PostgreSQL-Paritäts-Fixtures.
Python 3.11 oder neuer und uv.
Typst für die unterstützte Berichts-Rendering-Installation.
PostgreSQL-Befehlszeilenwerkzeuge einschließlich createdb für lokale Paritäts-Fixtures.
Ein gesundes ClineFlow/OKF-Bundle im Zielprojekt.
Führen Sie mcp-data-cli preflight aus, um erforderliche lokale Werkzeuge über einen verfügbaren Paketmanager im Benutzerbereich zu installieren oder zu melden. Es kontaktiert niemals eine konfigurierte Quelle. mcp-data-cli doctor validiert die lokale Installation; eine nicht konfigurierte Quelle wird als configuration_pending gemeldet, nicht als Installationsfehler.
Wenn ein Agent oder Betreiber gebeten wird, dieses GitHub-Repository in ein Projekt zu installieren, verwenden Sie den Repository-Installer – nicht einen bloßen uv tool install-Befehl:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bashDer Installer installiert das Befehlszeilenwerkzeug und initialisiert das Verzeichnis, aus dem es ausgeführt wurde. Er erstellt den ignorierten deterministischen Retail-Playground, schreibt den einen privaten MCP_DATA_SOURCE_URL-Wert in .env, schreibt die Quellenpolicy und führt den MCP-Server in jeden erkannten unterstützten Client zusammen. Er kopiert das Paket nicht in das Projekt und legt niemals eine Datenbank-URL oder Anmeldedaten in eine Client-Konfiguration. Client-Vertrauens-/Aktivierungs- und Neustartaufforderungen bleiben unter der Kontrolle jeder Client-Anwendung.
uv tool install installiert absichtlich ausführbare Dateien auf Benutzerebene und führt keine projektverändernden Post-Installations-Hooks aus. Verwenden Sie es nur, wenn Sie die ausführbare Datei separat installieren möchten, und führen Sie dann mcp-data-cli init selbst aus.
uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctorUm die aktuelle Repository-Version vor einer Paketveröffentlichung zu installieren, ersetzen Sie den Installationsbefehl durch:
uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.gitBei der ersten Serververwendung in einem unterstützten MCP-Client erstellt und öffnet der Agent einen deterministischen Entwicklungs-Only-Retail-SQLite-Playground unter .mcp-data/playground.sqlite. Das gemeinsame MCP-welcome-Werkzeug erklärt, wie man ihn erkundet und wie man zu einer echten Quelle wechselt. init materialisiert denselben Playground in die explizite Projektpolicy und private .env und führt dann nach einer Bestätigung sichere MCP-Client-Einträge zusammen. Der explizite Repository-Installer verwendet init --yes, da die Ausführung dieses Installers die einzige Autorisierung für diese begrenzten Schreibvorgänge ist.
Verwenden Sie setup --all, um nur die Client-Konfiguration in der Vorschau anzuzeigen, oder setup --all --apply, um nur den mcp-data-analysis-stdio-Eintrag nach einer expliziten Bestätigung zusammenzuführen. Es erhält nicht zusammenhängende Server und Einstellungen. Verwenden Sie setup --status, um die Erkennung und den aktuellen Konfigurationszustand zu prüfen.
Client | Bevorzugter Bereich | Fallback | Betreiberaktion nach dem Setup |
Claude Code | Projekt- | Benutzerkonfiguration | Projekt-Server-Genehmigung bei Aufforderung prüfen. |
VS Code / GitHub Copilot | Projekt- | Benutzer-MCP-Konfiguration | Neustart oder MCP-Serververwaltung verwenden; dem Server vertrauen. |
Cline, Cursor, Windsurf | Projekt-MCP-Konfiguration | Client-Benutzerkonfiguration | Client neu starten oder neu laden und den Server genehmigen/vertrauen. |
Continue | Projekt- | Benutzerkonfiguration | Continue neu starten und den Agent-Modus verwenden. |
Codex | — | Benutzer- | Codex neu starten; dies ist der enge Benutzerbereichs-Fallback. |
Das Setup konfiguriert nur MCP-Definitionen. Es kann die Vertrauens-/Aktivierungsaufforderung eines Clients nicht umgehen oder eine IDE starten/neu starten. Details zur VS-Code-Konfiguration sind in VS Code und GitHub Copilot in VS Code dokumentiert; Continue dokumentiert Projekt-MCP-Fragmente in seinem MCP-Leitfaden.
Für ein versioniertes Wheel und seine veröffentlichte SHA-256-Prüfsumme:
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.shDer Bootstrap erfordert curl und uv, verifiziert das Artefakt mit sha256sum oder shasum und installiert nur, wenn die Prüfsumme übereinstimmt. Er initialisiert dann das aktuelle Projekt genau wie der Repository-Installer. Er verwendet kein sudo und kontaktiert keine Produktionsdatenbank; er erstellt nur lokale deterministische Demo-Daten.
Die Standardinstallation verwendet genau eine aktive Quelle namens data und genau einen privaten Wert in .env: MCP_DATA_SOURCE_URL. Es ist keine Paketkonstante oder ein Testwert – es ist der eine Wert, den der Betreiber ändert, um auf seine eigene schreibgeschützte Datenbank zu verweisen. Halten Sie .env privat; es wird von Git ignoriert.
Bei der ersten Verwendung zeigt data automatisch auf den generierten Retail-Playground. Führen Sie mcp-data-cli init aus, wenn Sie bereit sind, diese Wahl in der Projekt-.env zu materialisieren; es schreibt:
MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'Der Playground besteht aus synthetischen Entwicklungs-Only-Daten. Er ermöglicht einer neuen Installation, Schemaerkennung, kontrollierte Abfragen, Belege und Berichte sofort auszuführen; es sind niemals Produktionsdaten und werden von einem späteren init-Lauf nie überschrieben. Alle unterstützten Clients erhalten dieselben stdio-Server-Begrüßungsanweisungen und das welcome-MCP-Werkzeug.
# .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'Für SQLite machen Sie dieselbe einzelne Variable zu einem absoluten Dateipfad oder einer SQLite-URL. Für PostgreSQL verwenden Sie eine postgres://- oder postgresql://-URL. Keine manuelle Dialekteinstellung ist erforderlich:
MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'Verwenden Sie data als Quellenargument in CLI-Aufrufen, zum Beispiel mcp-data-cli schema data. Der Agent lehnt nicht unterstützte URL-Schemata, relative SQLite-Pfade und einen veralteten deklarierten Dialekt ab, der mit der URL in Konflikt steht. Etablierte Multi-Quellen-Policies bleiben lesbar, aber init weigert sich bewusst, sie neu zu schreiben; migrieren Sie manuell oder starten Sie ein neues vereinfachtes Projekt.
Für PostgreSQL verwenden Sie ein dediziertes Konto mit geringsten Rechten und ohne Schreib- oder DDL-Berechtigungen. Der Agent aktiviert außerdem eine schreibgeschützte Sitzung und wendet den konfigurierten Schema-Suchpfad an, aber die Zugriffskontrolle auf Datenbankebene bleibt obligatorisch.
Vor der Ausführung validieren, dann den Plan prüfen und eine begrenzte Abfrage ausführen:
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 0Erstellen Sie eine explizite Aufgabe, wenn mehrere Operationen zu einer Analyse gehören:
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>Generieren Sie Berichte in einem neuen, vom Aufrufer gewählten Verzeichnis. Vorhandene Verzeichnisse und Symlink-Traversierung werden abgelehnt.
mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquetJeder Bericht enthält offline HTML, CSV, optionale Parquet/PDF-Artefakte, Belegmetadaten, Pfade und Inhalts-Hashes. Generierte Artefakte, Quellen und Anmeldedaten dürfen nicht eingecheckt werden.
init erstellt nur den oben beschriebenen kleinen Retail-Playground. Mitwirkende können zusätzliche deterministische synthetische Fixtures explizit generieren:
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 verwendet lokales createdb, lehnt einen vorhandenen Datenbanknamen ab, erstellt SQLite-Daten nur in einem temporären Verzeichnis und kopiert sie dann in die neue PostgreSQL-Datenbank unter dem mcp_parity-Schema. Es erfordert keine manuell bereitgestellte Wegwerf-PostgreSQL-URL.
seed-postgres ist für eine bereits bereitgestellte isolierte Testdatenbank. Es liest die private Test-URL aus der Umgebung und ersetzt nur deren reserviertes mcp_seed_retail-, mcp_seed_saas- oder mcp_seed_support-Schema. Es berührt niemals öffentliche/Anwendungsschemata.
Führen Sie die vollständige lokale Qualitätssuite mit einer isolierten PostgreSQL-Instanz aus, wenn Sie Adapterverhalten entwickeln. CI umfasst Linting, Typprüfung, Tests, Abdeckungsgrenzen, echtes Typst-Rendering, SQLite/PostgreSQL-Parität, Secret-Scanning, Abhängigkeitsprüfung, SBOM-Erzeugung und vertrauenswürdige Veröffentlichungsautomatisierung.
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-okfSicherheitskritische Konfigurations-, Kontext-, Ledger- und SQL-Policy-Module erfordern 100 % Zeilen- und Zweigabdeckung. Gesamtgrenzen erfordern mindestens 90 % Zeilenabdeckung und 85 % Zweigabdeckung.
Abfragen müssen parametrisiert sein und werden vor Datenbankverbindung/-ausführung validiert.
Ergebnisgrenzen und Offsets werden durch die Projektpolicy geregelt; Aufrufer-SQL kann sie nicht umgehen.
Eingeschränkte Spalten werden vor der Ausführung abgelehnt und geheimnisähnliche Parameter werden in Beobachtbarkeitsdatensätzen redigiert.
Aufgabenjournale, Abfragebelege, Ausführungen und Ereignisse werden unter knowledge/ und observability/ gespeichert; Datenbank-URLs, rohe Geheimnisse, Quelldatenbanken, Ergebnis-Caches und Berichtsbinärdateien sind ausgeschlossen.
Lokale synthetische Datensätze sind nur Entwicklungsinfrastruktur und keine Produktions-Onboarding.
Siehe Betriebsanleitung, die Sicherheitsrichtlinie und die MIT-Lizenz für den vollständigen Betriebs- und Offenlegungsvertrag.
Verwenden Sie fokussierte Commits und bewahren Sie die annotierten checkpoint-*-Tags: Sie sind explizite Rollback-Punkte für Liefermeilensteine. Aktualisieren Sie das aktive ClineFlow-Engineering-Journal und das Wissensprotokoll mit wesentlichen Änderungen, führen Sie die OKF-Validierung aus und committen Sie dann Implementierung und Wissensnachweise zusammen.
GitHub Actions erstellt und verifiziert Distributionen bei der Veröffentlichung. Veröffentlichungsendpunkte und Veröffentlichungsanmeldedaten sind Repository-Konfiguration; sie werden niemals in dieser Codebasis gespeichert.
| 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.
