Локально-ориентированная, управляемая аналитика для MCP-клиентов поверх SQLite и PostgreSQL.
mcp-data-analysis-agent предоставляет MCP-клиенту небольшой, проверяемый слой доступа к данным вместо прямого доступа к базе данных. Он проверяет SQL перед выполнением, использует соединения только для чтения, ограничивает результаты и время выполнения, записывает записи наблюдаемости с подтверждениями и хранит учётные данные на машине оператора.
MCP-клиенты могут рассуждать о данных, но им не следует выдавать неограниченные учётные данные базы данных или позволять незаметно выполнять произвольные операторы. Этот проект предоставляет локальную контрольную точку для этой границы:
Храните пути к базам данных, URL-адреса, пароли и токены в игнорируемом файле .env.
Разрешайте только один параметризованный оператор SELECT или WITH.
Блокируйте мутации, DDL, команды, вложения, многооператорные запросы, небезопасные функции, ограниченные поля и небезопасные пути к артефактам.
Требуйте доступ только для чтения на уровне базы данных в дополнение к политике приложения.
Сохраняйте нормализованный SQL, время выполнения, привязку к задачам, подтверждения, хэши и временные шкалы событий для последующего аудита.
Сервер использует только stdio. Он не размещает публичный API, не загружает исходные данные, не хранит удалённые учётные данные и не создаёт пользователей производственной базы данных.
Related MCP server: sql-explorer-mcp
Доступ к SQLite и PostgreSQL через SQLAlchemy Core с проверкой политики SQLGlot.
Обнаружение источников, схем, связей, профилей, качества/свежести и дрейфа схем.
Проверка, планы объяснения, ограниченное выполнение, пагинация со смещением без отрицательных значений, отмена, тайм-ауты и ограничения параллелизма.
Классификации для публичных, внутренних, конфиденциальных и ограниченных полей/источников.
Одобренные семантические метрики, Git-нативные рецепты, сравнение периодов, обнаружение изменений и рекомендации по диаграммам.
Офлайн HTML-дашборды, CSV, Parquet, Typst PDF, метаданные подтверждений и безопасные атомарные выходные каталоги.
Загрузка контекста ClineFlow, журналы задач, неизменяемые записи запросов/выполнений, временные шкалы событий и проверка целостности.
Детерминированные фикстуры для розничной торговли, SaaS и поддержки, включая локальные фикстуры паритета SQLite-к-PostgreSQL.
Python 3.11 или новее и uv.
Typst для поддерживаемой установки рендеринга отчётов.
Инструменты командной строки PostgreSQL, включая createdb для локальных фикстур паритета.
Работоспособный пакет 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Установщик устанавливает инструмент командной строки и инициализирует каталог, из которого он был запущен.
Он создаёт игнорируемую детерминированную розничную песочницу, записывает единственное приватное
значение 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-клиенте агент создаёт и открывает детерминированную розничную SQLite-песочницу только для разработки в .mcp-data/playground.sqlite. Общий MCP-инструмент welcome объясняет, как её исследовать и как переключиться на реальный источник. init материализует ту же песочницу в явную политику проекта и приватный .env, затем объединяет безопасные записи MCP-клиента после одного подтверждения. Явный установщик репозитория использует init --yes, потому что запуск этого установщика является единственной авторизацией для этих ограниченных записей.
Используйте setup --all для предварительного просмотра конфигурации клиента или setup --all --apply для объединения только записи stdio mcp-data-analysis после одного явного подтверждения. Он сохраняет несвязанные серверы и настройки. Используйте 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 и GitHub Copilot в VS Code; 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 и ровно одно приватное значение в .env: MCP_DATA_SOURCE_URL. Это не константа пакета и не тестовое значение — это единственное значение, которое оператор меняет, чтобы указать на свою собственную базу данных только для чтения. Держите .env в тайне; он игнорируется Git.
При первом использовании data автоматически указывает на сгенерированную розничную песочницу. Запустите mcp-data-cli init, когда будете готовы материализовать этот выбор в проектном .env; он записывает:
MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'Песочница — это синтетические данные только для разработки. Она позволяет новой установке немедленно выполнять обнаружение схем, управляемые запросы, подтверждения и отчёты; это никогда не производственные данные и никогда не перезаписывается последующим запуском init. Все поддерживаемые клиенты получают одинаковые инструкции приветствия stdio-сервера и MCP-инструмент welcome.
# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30
# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"
[classification.columns]
email = "restricted"# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'Для SQLite сделайте ту же единственную переменную абсолютным путём к файлу или URL-адресом SQLite. Для PostgreSQL используйте URL-адрес postgres:// или postgresql://. Ручная настройка диалекта не требуется:
MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'Используйте data в качестве аргумента источника в вызовах CLI, например 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Создайте явную задачу, когда несколько операций принадлежат одному анализу:
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 только во временном каталоге, а затем копирует их в новую базу данных PostgreSQL в схеме mcp_parity. Он не требует вручную указанного одноразового URL-адреса PostgreSQL.
seed-postgres предназначен для уже подготовленной изолированной тестовой базы данных. Он читает приватный тестовый URL из окружения и заменяет только свои зарезервированные схемы mcp_seed_retail, mcp_seed_saas или mcp_seed_support. Он никогда не касается публичных/прикладных схем.
Запустите полный локальный набор проверки качества с изолированным экземпляром 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.
