SQLite と PostgreSQL 上の MCP クライアント向けの、ローカルファーストでガバナンスされた分析基盤です。
mcp-data-analysis-agent は、MCP クライアントにデータベースへの直接アクセスの代わりに、小さく監査可能なデータアクセス層を提供します。SQL を実行前に検証し、読み取り専用接続を使用し、結果と実行時間を制限し、レシート付きの可観測性レコードを書き込み、認証情報はオペレーターのマシン上に保持します。
MCP クライアントはデータについて推論できますが、無制限のデータベース認証情報を受け取ったり、任意のステートメントを黙って実行したりすべきではありません。このプロジェクトは、その境界に対するローカルな制御ポイントを提供します:
データベースのパス、URL、パスワード、トークンを無視される .env ファイルに保持します。
パラメータ化された単一の SELECT または WITH ステートメントのみを許可します。
変更、DDL、コマンド、アタッチメント、複数ステートメント、安全でない関数、制限付きフィールド、安全でないアーティファクトパスをブロックします。
アプリケーションポリシーに加えて、データベースレベルの読み取り専用アクセスを要求します。
正規化された SQL、タイミング、タスクリンク、レシート、ハッシュ、イベントタイムラインを後で監査できるように保持します。
サーバーは stdio のみを使用します。公開 API をホストせず、ソースデータをアップロードせず、リモート認証情報を保存せず、本番データベースユーザーを作成しません。
Related MCP server: sql-explorer-mcp
SQLAlchemy Core と SQLGlot ポリシー検証による SQLite および PostgreSQL アクセス。
ソース、スキーマ、リレーションシップ、プロファイル、品質/鮮度、スキーマドリフトの検出。
検証、実行計画の説明、制限付き実行、非負オフセットページネーション、キャンセル、タイムアウト、同時実行制限。
公開、内部、機密、制限付きフィールド/ソースの分類。
承認済みセマンティックメトリクス、Git ネイティブレシピ、期間比較、変更検出、チャート推奨。
オフライン HTML ダッシュボード、CSV、Parquet、Typst PDF、レシートメタデータ、安全なアトミック出力ディレクトリ。
ClineFlow コンテキストロード、タスクジャーナル、不変のクエリ/実行レコード、イベントタイムライン、整合性検証。
決定的な小売、SaaS、サポートフィクスチャ。ローカル SQLite から PostgreSQL へのパリティフィクスチャを含みます。
Python 3.11 以降と uv。
サポートされているレポートレンダリングインストール用の Typst。
ローカルパリティフィクスチャ用の createdb を含む PostgreSQL コマンドラインツール。
対象プロジェクト内の健全な ClineFlow/OKF バンドル。
mcp-data-cli preflight を実行して、利用可能なユーザースコープのパッケージマネージャーを通じて必要なローカルツールをインストールまたは報告します。設定されたソースに連絡することはありません。mcp-data-cli doctor はローカルインストールを検証します。設定されたソースがない場合は configuration_pending として報告され、インストール失敗とは見なされません。
エージェントまたはオペレーターがこの GitHub リポジトリをプロジェクトにインストールするよう求められた場合は、リポジトリインストーラーを使用してください。裸の uv tool install コマンドではありません:
cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bashインストーラーはコマンドラインツールをインストールし、実行されたディレクトリを初期化します。無視される決定的な小売プレイグラウンドを作成し、1 つのプライベートな MCP_DATA_SOURCE_URL 値を .env に書き込み、ソースポリシーを書き込み、検出されたすべてのサポート対象クライアントに MCP サーバーをマージします。パッケージをプロジェクトにコピーせず、データベース URL や認証情報をクライアント設定に入れることはありません。クライアントの信頼/有効化と再起動プロンプトは、各クライアントアプリケーションの制御下にあります。
uv tool install は意図的にユーザーレベルの実行可能ファイルをインストールし、プロジェクトを変更するポストインストールフックを実行しません。実行可能ファイルを個別にインストールし、その後自分で mcp-data-cli init を実行する場合にのみ使用してください。
uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctorパッケージリリース前に現在のリポジトリバージョンをインストールするには、インストールコマンドを次に置き換えます:
uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.gitサポートされている MCP クライアントでの最初のサーバー使用時に、エージェントは .mcp-data/playground.sqlite に決定的な開発専用小売 SQLite プレイグラウンドを作成して開きます。共有 MCP welcome ツールは、その探索方法と実際のソースへの切り替え方法を説明します。init は同じプレイグラウンドを明示的なプロジェクトポリシーとプライベートな .env に具体化し、1 回の確認後に安全な MCP クライアントエントリをマージします。明示的なリポジトリインストーラーは init --yes を使用します。これは、そのスコープの書き込みに対する単一の承認であるためです。
setup --all を使用してクライアント設定のみをプレビューするか、setup --all --apply を使用して 1 回の明示的な確認後に mcp-data-analysis stdio エントリのみをマージします。無関係なサーバーと設定は保持されます。setup --status を使用して検出と現在の設定状態を検査します。
クライアント | 推奨スコープ | フォールバック | セットアップ後のオペレーターアクション |
Claude Code | プロジェクト | ユーザー設定 | プロンプトが表示されたら、プロジェクトサーバーの承認を確認します。 |
VS Code / GitHub Copilot | プロジェクト | ユーザー MCP 設定 | 再起動するか、MCP サーバー管理を使用します。サーバーを信頼します。 |
Cline, Cursor, Windsurf | プロジェクト MCP 設定 | クライアントユーザー設定 | クライアントを再起動またはリロードし、サーバーを承認/信頼します。 |
Continue | プロジェクト | ユーザー設定 | Continue を再起動し、Agent モードを使用します。 |
Codex | — | ユーザー | Codex を再起動します。これは狭いユーザースコープのフォールバックです。 |
セットアップは MCP 定義のみを構成します。クライアントの信頼/有効化プロンプトをバイパスしたり、IDE を起動/再起動したりすることはできません。VS Code の設定詳細は VS Code と VS Code の GitHub Copilot に文書化されています。Continue はプロジェクト MCP フラグメントを MCP ガイド で文書化しています。
バージョン付きホイールとその公開 SHA-256 チェックサムの場合:
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.shブートストラップには curl と uv が必要で、sha256sum または shasum でアーティファクトを検証し、チェックサムが一致した場合のみインストールします。その後、リポジトリインストーラーとまったく同じように現在のプロジェクトを初期化します。sudo を使用せず、本番データベースに連絡しません。ローカルの決定的なデモデータのみを作成します。
標準インストールでは、data という名前のアクティブなソースが 1 つだけ、.env にプライベートな値が 1 つだけあります: MCP_DATA_SOURCE_URL。これはパッケージ定数やテスト値ではなく、オペレーターが自分の読み取り専用データベースを指すように変更する唯一の値です。.env はプライベートに保ち、Git で無視されます。
初回使用時、data は自動的に生成された小売プレイグラウンドを指します。その選択をプロジェクトの .env に具体化する準備ができたら mcp-data-cli init を実行します。次のように書き込みます:
MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'プレイグラウンドは開発専用の合成データです。新しいインストールがスキーマ検出、ガバナンスされたクエリ、レシート、レポートをすぐに実行できるようにします。本番データではなく、後の init 実行で上書きされることもありません。すべてのサポート対象クライアントは、同じ stdio サーバーのウェルカム手順と welcome MCP ツールを受け取ります。
# .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'SQLite の場合、同じ単一の変数を絶対ファイルパスまたは SQLite URL にします。PostgreSQL の場合、postgres:// または postgresql:// URL を使用します。手動の方言設定は不要です:
MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'CLI 呼び出しでは data をソース引数として使用します。例: mcp-data-cli schema data。エージェントは、サポートされていない URL スキーム、相対 SQLite パス、URL と競合するレガシー宣言方言を拒否します。確立されたマルチソースポリシーは読み取り可能なままですが、init はそれらを書き換えることを意図的に拒否します。手動で移行するか、新しい簡素化されたプロジェクトを開始してください。
PostgreSQL の場合、書き込みや DDL 権限のない専用の最小権限アカウントを使用します。エージェントは読み取り専用セッションも有効にし、設定されたスキーマ検索パスを適用しますが、データベース側のアクセス制御は必須のままです。
実行前に検証し、計画を検査して、制限付きクエリを実行します:
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 0複数の操作が 1 つの分析に属する場合は、明示的なタスクを作成します:
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>呼び出し元が選択した新しいディレクトリにレポートを生成します。既存のディレクトリとシンボリックリンクのトラバーサルは拒否されます。
mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet各レポートには、オフライン HTML、CSV、オプションの Parquet/PDF アーティファクト、レシートメタデータ、パス、コンテンツハッシュが含まれます。生成されたアーティファクト、ソース、認証情報はコミットしてはなりません。
init は上記の小さな小売プレイグラウンドのみを作成します。コントリビューターは、追加の決定的な合成フィクスチャを明示的に生成できます:
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 はローカルの createdb を使用し、既存のデータベース名を拒否し、SQLite データを一時ディレクトリにのみ作成し、それを mcp_parity スキーマの下の新しい PostgreSQL データベースにコピーします。手動で使い捨ての PostgreSQL URL を提供する必要はありません。
seed-postgres は、既にプロビジョニングされた分離されたテストデータベース用です。環境からプライベートなテスト URL を読み取り、予約された mcp_seed_retail、mcp_seed_saas、または mcp_seed_support スキーマのみを置き換えます。public/アプリケーションスキーマには触れません。
アダプターの動作を開発するときは、分離された PostgreSQL インスタンスで完全なローカル品質スイートを実行します。CI は、リンティング、型チェック、テスト、カバレッジゲート、実際の Typst レンダリング、SQLite/PostgreSQL パリティ、シークレットスキャン、依存関係監査、SBOM 生成、信頼できる公開リリース自動化をカバーします。
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-okf安全上重要な設定、コンテキスト、台帳、SQL ポリシーモジュールは、100% の行とブランチのカバレッジを必要とします。全体のゲートは、少なくとも 90% の行カバレッジと 85% のブランチカバレッジを必要とします。
クエリはパラメータ化され、データベース接続/実行前に検証されます。
結果の制限とオフセットはプロジェクトポリシーによって管理されます。呼び出し元の SQL はそれらをバイパスできません。
制限付き列は実行前に拒否され、シークレットのようなパラメータは可観測性レコードで編集されます。
タスクジャーナル、クエリレシート、実行、イベントは knowledge/ と observability/ の下に保存されます。データベース URL、生のシークレット、ソースデータベース、結果キャッシュ、レポートバイナリは除外されます。
ローカル合成データセットは開発インフラストラクチャのみであり、本番オンボーディングではありません。
完全な運用および開示契約については、運用ガイダンス、セキュリティポリシー、MIT ライセンス を参照してください。
焦点を絞ったコミットを使用し、注釈付きの checkpoint-* タグを保持してください。これらは配信マイルストーンの明示的なロールバックポイントです。アクティブな ClineFlow エンジニアリングジャーナルとナレッジログを重要な変更で更新し、OKF 検証を実行してから、実装とナレッジの証拠を一緒にコミットします。
GitHub Actions は、リリース公開時にディストリビューションをビルドして検証します。リリースエンドポイントと公開認証情報はリポジトリ設定です。このコードベースに保存されることはありません。
| 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.
