Skip to main content
Glama
deenesjakoruzh
SurajKGoyal

amnesic

by SurajKGoyal
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

amnesic —— 注册表中名字最具讽刺意味的 MCP 服务器

PyPI version Python License: MIT MCP Registry Glama score

你数据库的机构记忆，以 MCP 服务器的形式呈现。名字是讽刺的——它什么都记得。

"注册表中名字最具讽刺意味的 MCP 服务器。它一点也不健忘——它记住你的数据库，这样你的 AI 就不必记了。"

大多数数据库 MCP 服务器都是查询执行器：它们连接、内省、运行 SQL，然后遗忘。amnesic 是一种语义记忆——它积累你的模式意味着什么（status = 3 是什么，哪些列实际上是外键，那个遗留表是干什么用的），并自动将其交给每一个未来的会话。可以把它想象成数据目录，减去平台、摄取管道和账单。amnesic 的定位 ↓

兼容 Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf —— 任何 MCP 兼容客户端。

可在 官方 MCP 注册表 · Claude Code 插件市场 获取

👋 正在使用 amnesic？ 在 adopters 讨论帖中打个招呼 —— 下载量无法告诉我实际使用情况，而这直接决定了接下来构建什么。

🔒 设计上只读。 amnesic 拒绝执行 INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、MERGE、GRANT、REVOKE —— 以及任何藏在 WITH CTE 中的写语句。两层防御：静态 SQL 分析在连接之前就拒绝该语句，并且每个查询都在一个立即回滚的事务中运行。可以放心指向生产环境。详情 ↓

问题

每次与 AI 的会话都是冷启动。你花前几分钟重新解释存在哪些表、status 列的值 3 是什么意思、哪个外键连接了 orders 和 users。然后会话结束，明天你又得从头再来一遍。

amnesic 解决了这个问题。 它给你的 AI 一个持久的 SQLite 知识存储——每个数据库一个——跨会话存续。注释一次状态枚举；未来的每个会话都会自动看到这些标签。发现一次外键关系；未来的每个 JOIN 查询都会使用该图。

这些知识也是可移植的，并且比你对数据库的访问权限活得更久。当你轮换离开一个项目时，amnesic export 将你教给它的所有东西交给下一位开发者——那些"哦，那列实际上意味着……"的多年积累，否则就会随你一起离开。

Related MCP server: engram-mcp

amnesic 的定位

数据库 MCP 生态系统分为两个阵营，而 amnesic 刻意不属于任何一个。

查询执行器 —— DBHub、Postgres MCP Pro、Google 的 MCP Toolbox 以及各厂商服务器（Supabase、Neon）。它们实时内省、运行 SQL，有些在性能方面做得很深入——Postgres MCP Pro 做真正的索引调优和 PgHero 风格的健康检查。它们在这方面非常出色。但它们也是无状态的：每个会话都从头重新学习你的模式，而且它们返回的任何内容都无法告诉你某列意味着什么，因为数据库本身也不知道。

企业目录 —— DataHub、Atlan、Cube、AtScale。这些确实持有语义上下文：词汇表、列描述、所有权、血缘关系。但它们也是一种平台承诺——元数据摄取、需要运行的服务、通常还有付费层级。在公司规模下值得；但对于一个需要记住遗留 MSSQL 数据库中六个状态代码含义的开发者来说，这严重不成比例——那个数据库永远不会有人接入目录。

amnesic 是第三种东西：目录级的语义记忆，却只有查询执行器的搭建成本。pipx install、一个 TOML 文件、每个数据库一个本地 SQLite 文件。没有平台、没有摄取、没有需要运行的服务器。

诚实的对比

amnesic

查询执行器

企业目录

语义上下文（值意味着什么）

✅ 持久的，属于你

❌ 无

✅ 平台管理

跨会话存续

✅

❌

✅

可移植 / 比数据库访问权限活得更久

✅ export/import

❌

⚠️ 受平台限制

搭建成本

一条命令

一条命令

摄取管道

实时模式新鲜度

⚠️ 缓存，手动刷新

✅ 始终实时

⚠️ 摄取延迟

执行计划 / 索引调优

❌

✅（Postgres MCP Pro）

❌

血缘 / 所有权 / 治理

❌

❌

✅

适用于没有外键约束的遗留模式

✅ 自己注释它们

❌ 没有可内省的内容

⚠️ 需要摄取

如果你想要执行计划、索引建议或数据库健康诊断，请使用查询执行器而不是 amnesic——那不是 amnesic 的职责，加上它只会让它变成一个已有工具的劣化版本。

将 amnesic 与查询执行器一起使用。 它们可以组合：没有任何东西阻止你同时运行两者。amnesic 持有含义；它们持有机制。

上面标记 ⚠️ 的行是已知的差距，有对应的开放 issue——参见 路线图 ↓。

快速开始（90 秒）

pipx install amnesic            # install the core
amnesic init                    # interactive wizard

⚡ 无需凭据即可试用。 改为运行 amnesic init --demo——它会添加一个自包含的 SQLite 示例数据库（电商模式：customers / products / orders，带外键和一个枚举列），让你在一分钟内体验每个工具。在将 amnesic 指向真实数据库之前，非常适合先看一眼。

向导会询问你要连接哪种数据库类型，并告诉你如果其驱动尚未安装时需要运行的那一条命令——你永远不需要提前猜测额外的依赖。

向导：

  • 询问你的数据库类型、主机和凭据

  • 在保存任何内容之前测试连接

  • 将密码安全地存储在 ~/.config/amnesic/.env 中（chmod 600）

  • 将连接块写入 ~/.config/amnesic/connections.toml

然后将 amnesic 添加到你的 AI 客户端并重启。

安装 pipx（一次性）：

brew install pipx                                  # macOS
sudo apt install pipx                              # Linux (Debian/Ubuntu)
python -m pip install --user pipx                  # Windows / generic

或者使用 uv（单二进制替代方案——快速，无需 Python）：

brew install uv                                            # macOS
curl -LsSf https://astral.sh/uv/install.sh | sh            # Linux / macOS
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows

uv tool install amnesic

或者普通 pip（安装到你当前激活的 Python 环境中）：

pip install amnesic

无论你选择哪个，amnesic init 都会询问你将连接哪个数据库，并打印安装该驱动所需的那一条额外命令——无需提前承诺额外的依赖。

安装后，amnesic --help 可在任何终端中使用。

amnesic 存储内容的位置

文件

macOS / Linux

Windows

配置

~/.config/amnesic/connections.toml

%APPDATA%\amnesic\connections.toml

密钥

~/.config/amnesic/.env（chmod 600）

%APPDATA%\amnesic\.env（用户配置文件 ACL）

知识

~/.config/amnesic/knowledge_<name>.db

%APPDATA%\amnesic\knowledge_<name>.db

设置 $AMNESIC_HOME（或在 Linux 上设置 $XDG_CONFIG_HOME）来覆盖位置。

之后添加更多连接

amnesic add          # add another connection to existing config
amnesic test         # verify all connections
amnesic test orders.prod  # verify one connection

设置和轮换密码

amnesic init 和 amnesic add 会自动保存你的密码——对于典型的设置流程，你永远不需要考虑这一节。

当你之后需要更改已存储的密码时，使用 set-secret——IT 轮换了密码、你在设置时打错了字，或者你在手动编辑配置。

$ amnesic set-secret ORDERS_PROD_PASSWORD
Value: ****            ← hidden input (your typing is invisible)
Confirm: ****
✓ Set ORDERS_PROD_PASSWORD in ~/.config/amnesic/.env

变量名是什么？ 它是你的 connections.toml 中为该连接的密码引用的环境变量。向导会自动生成这些为 <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_PASSWORD：

连接名称

生成的环境变量

orders.prod

ORDERS_PROD_PASSWORD

analytics

ANALYTICS_PASSWORD

drive.staging

DRIVE_STAGING_PASSWORD

要查看你的配置使用的确切名称，请检查 ~/.config/amnesic/connections.toml——${...} 内的任何内容都是要传给 set-secret 的变量。

底层原理：写入（或替换）~/.config/amnesic/.env 中的那一行，将文件权限设置为 chmod 600（只有你的用户能读取），保留所有其他条目。

管理连接和知识

知识按连接累积在本地 SQLite 文件中。以下命令让你在机器之间移动它并进行清理：

# Hand off everything you've taught amnesic about a database (annotations +
# relationships, not the re-derivable schema cache) as portable JSON:
amnesic export orders.prod -o orders-knowledge.json
amnesic export orders.prod            # or print to stdout to pipe/redirect

# Load that knowledge into another connection (e.g. promote staging → prod,
# or onboard a teammate). Unconditional upsert — existing entries are overwritten:
amnesic import orders.prod orders-knowledge.json

# Wipe stored knowledge for a connection but keep the config entry:
amnesic clear orders.staging

# Drop a connection from connections.toml entirely (knowledge file kept
# unless you pass --delete-knowledge):
amnesic remove old.connection
amnesic remove old.connection --delete-knowledge

export/import/clear/remove 纯粹操作本地文件——它们从不连接数据库，因此即使某个连接的凭据未设置也能工作。remove 通过外科手术式的字符串编辑来修改 connections.toml，使其他所有块的格式和注释逐字节保持不变。

添加到你的 AI 客户端

一旦 amnesic 安装了正确的驱动 extras（参见快速开始），amnesic 命令就在你的 PATH 上。在每个 MCP 客户端中使用相同的片段：

Claude Code

一行安装（推荐——无需编辑 JSON）。在 Claude Code 内部：

/plugin marketplace add https://github.com/SurajKGoyal/amnesic-marketplace
/plugin install amnesic@amnesic

这会自动将 amnesic 作为 MCP 服务器接入。来源：SurajKGoyal/amnesic-marketplace。

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Claude Desktop

添加到你的平台的 Claude Desktop 配置中：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows：%APPDATA%\Claude\claude_desktop_config.json

  • Linux：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

Cursor

一键安装——点击下面的按钮，Cursor 会为你完成接入：

添加到项目中的 .cursor/mcp.json（或全局的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "amnesic": {
      "command": "amnesic"
    }
  }
}

无需全局安装（临时）

如果你不想在系统上安装 amnesic，可以使用 uvx 或 pipx 在每次 MCP 客户端启动时获取它。注意必须显式传递驱动 extras：

// uvx — requires `uv` installed (see Install section for per-OS instructions)
{
  "mcpServers": {
    "amnesic": {
      "command": "uvx",
      "args": ["--from", "amnesic[mssql]", "amnesic"]
    }
  }
}

// pipx — usually pre-installed via Homebrew or system package manager
{
  "mcpServers": {
    "amnesic": {
      "command": "pipx",
      "args": ["run", "--spec", "amnesic[mssql]", "amnesic"]
    }
  }
}

对于多个驱动，在方括号内用逗号分隔——例如 amnesic[postgres,mssql]，或者使用 amnesic[all] 安装全部。

VS Code（带 MCP 扩展）

添加到 .vscode/mcp.json：

{
  "servers": {
    "amnesic": {
      "type": "stdio",
      "command": "amnesic"
    }
  }
}

更新

amnesic 发布频繁。使用你安装它的同一个工具升级：

安装方式

升级命令

pipx

pipx upgrade amnesic

uv tool

uv tool upgrade amnesic

pip

pip install --upgrade amnesic

uvx（临时，位于你的 MCP 配置中）

uvx 会缓存构建产物——运行 uv cache clean amnesic 以拉取最新版本

然后重启你的 MCP 客户端（Claude Code、Cursor 等），让它重新启动 amnesic 服务器并加载任何新工具。

升级是安全的——你不会丢失任何注解。 你的知识文件会在首次加载时自动迁移到新 schema；amnesic 只会新增列，绝不会删除你的数据。

查看已安装版本：amnesic --version。最新版本：PyPI · Releases。

工具

工具

描述

db_list_connections()

列出所有已配置的连接（不暴露任何机密信息）

db_list_tables(connection)

所有已知表及其描述和列数量

db_search(query, connection, target, limit)

对表/列描述和别名进行 BM25 搜索

db_get_schema(table, connection)

列 schema 与已保存的注解合并后的结果

db_query(sql, connection)

执行只读 SELECT 查询

db_annotate(table, connection, ...)

持久化表/列的语义注解

db_deprecate(table, connection, column?, reason?, undo?)

软弃用过时注解——标记（并警告）但保留，可撤销

db_detect_drift(connection)

审计注解与实时 schema 的差异——发现孤立注解和未文档化的表

db_forget(table, connection, column?, cascade?)

硬删除注解（级联可选）——永久性

db_sync_knowledge(from, to)

在连接之间复制注解（例如 staging → prod）

db_discover_relationships(connection)

从实时数据库中发现所有外键关系

db_get_relationships(table, connection)

浏览外键图以规划 JOIN

搜索知识库

对于大型 schema，db_list_tables 并不实用——你会把 500 多行数据倾倒进 Claude 的上下文中。请改用 db_search 按关键字查找相关表/列：

"What table tracks customer payments?"
  → db_search("payments")
    Top results:
      - dbo.payments  (table) "Customer payment records..."
      - dbo.orders.payment_method  (column) "Mode of payment..."

db_search 使用 SQLite FTS5 与 BM25 排序——快速、本地化，无需嵌入或外部服务。搜索语法支持：

语法

效果

payment

匹配该词（带词干提取——也会匹配 "payments"、"paying"）

"payment method"

精确短语

pay*

前缀匹配——"payment"、"payable" 等

payment AND status

两个词都必须出现

payment OR refund

任一词出现即可

结果返回带描述和高亮片段的排序后的表/列行。

知识层

核心差异化优势。每条注解都能在重启、模型更新和新会话后继续存活。

会话 1——你发现了某些东西

You: What does status=3 mean in the orders table?
AI: Let me check. [runs db_query: SELECT DISTINCT status FROM dbo.orders]
    I see values 1, 2, 3, 4. Let me look at some examples...
    Based on the data, 3 appears to be "cancelled".

You: Save that. And status=1 is "pending", 2 is "confirmed", 4 is "delivered".
AI: [calls db_annotate]
    db_annotate(
      table="dbo.orders",
      column="status",
      column_description="Order lifecycle status",
      enum_values={"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}
    )
    Saved. Future sessions will see these labels automatically.

会话 2——知识已经在那里了

You: How many cancelled orders are there this month?
AI: [calls db_get_schema("dbo.orders")]
    Schema response includes:
      column: "status"
      description: "Order lifecycle status"
      enum_values: {"1": "pending", "2": "confirmed", "3": "cancelled", "4": "delivered"}

    [writes correct SQL immediately]
    SELECT COUNT(*) FROM dbo.orders WHERE status = 3 AND ...

无需重新发现。不浪费任何轮次。注解被持久化了。

关系图

一次理解你的 schema 的 JOIN 结构，永久复用。

AI: [db_discover_relationships(connection="orders.prod")]
    Discovered 47 foreign key relationships.

AI: [db_get_relationships(table="orders", depth=2)]
    neighbors:
      orders → users (via user_id → id)
      orders → order_items (via id ← order_id)
    paths:
      orders -> users
      orders -> order_items
      order_items -> products

现在 AI 确切地知道如何跨 schema 进行 JOIN，无需猜测。

环境间同步

在 staging 中积累注解，然后提升到 prod：

db_sync_knowledge(from_connection="orders.staging", to_connection="orders.prod")

返回 {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}。

目标 schema 缓存中缺失的表会被跳过，并附有明确原因。目标 schema 中缺失的列会产生警告，但不会阻塞其余同步。

高级：手动编辑 TOML

如果你更愿意自己管理配置文件，可以生成一个空白模板：

amnesic init --template

这会写入 ~/.config/amnesic/connections.toml，包含带注释的示例并退出——不启动向导。直接编辑该文件：

# ~/.config/amnesic/connections.toml

# Nested style: [connections.product.env]
[connections.orders.prod]
driver = "mssql"
server = "localhost"
port = 11433
database = "OrdersDB"
user = "${ORDERS_USER}"
password = "${ORDERS_PROD_PASSWORD}"
tunnel_script = "~/.scripts/mssql-tunnel.sh"     # macOS / Linux (bash)
# tunnel_script = "C:/scripts/mssql-tunnel.ps1"  # Windows (PowerShell)

[connections.orders.staging]
driver = "mssql"
server = "localhost"
port = 11434
database = "OrdersDB_Staging"
user = "${ORDERS_USER}"
password = "${ORDERS_STAGING_PASSWORD}"

# Flat style: [connections.name]
[connections.analytics]
driver = "postgres"
server = "analytics.company.com"
port = 5432
database = "warehouse"
user = "${ANALYTICS_DB_USER}"
password = "${ANALYTICS_DB_PASSWORD}"

# SQLite — no credentials needed
[connections.local]
driver = "sqlite"
database = "/absolute/path/to/local.db"       # macOS / Linux
# database = "C:/path/to/local.db"            # Windows (use forward slashes)

使用 ${ENV_VAR} 存放凭据——切勿硬编码密码。

机密信息会自动从 ~/.config/amnesic/.env 加载（格式：KEY=VALUE，每行一个，# 表示注释）。对于 TOML 中引用的每个 ${VAR_NAME}，使用 amnesic set-secret VAR_NAME（隐藏输入，chmod 600）填充对应的 .env 条目，或自行编写 .env。

规范连接名称使用点号表示法：orders.prod、orders.staging、analytics、local。

支持的数据库

数据库

Python 驱动

安装方式

PostgreSQL

psycopg2-binary

选择 Postgres 时向导提示，或 amnesic[postgres] 附加包

MySQL / MariaDB

pymysql

选择 MySQL 时向导提示，或 amnesic[mysql] 附加包

Microsoft SQL Server

pymssql

选择 MSSQL 时向导提示，或 amnesic[mssql] 附加包

SQLite

标准库 sqlite3

始终可用——无需额外安装

安全与只读强制

amnesic 的设计目标就是可以安全地指向生产数据库。

为什么你的 AI 无法损坏你的数据

每条查询在到达数据库之前都要经过两个独立的层：

  1. 静态分析（位于 amnesic/readonly.py）——SQL 会被分词，如果包含以下任何关键字则被拒绝： INSERT、UPDATE、DELETE、DROP、TRUNCATE、ALTER、CREATE、EXEC、EXECUTE、MERGE、BULK、GRANT、REVOKE、DENY。 这包括隐藏在 CTE 中的写语句（WITH x AS (SELECT ...) UPDATE ... 会被捕获并拒绝）。

  2. 事务回滚——即使写语句以某种方式通过了静态检查，查询也会在 BEGIN TRANSACTION ... ROLLBACK 内运行，因此永远不会提交任何内容。双保险。

只有 SELECT 和 WITH ... SELECT 能到达数据库。注释会在分析前被剥离，因此 /* DELETE FROM users */ 无法被用来隐藏攻击。

其他安全措施

  • 响应中不含凭据：db_list_connections 会从其输出中剥离密码和用户名。AI 可以看到存在哪些连接，但永远看不到如何认证。

  • 凭据仅通过环境变量：在配置加载时进行 ${ENV_VAR} 展开——密码永远不会写入磁盘上的 connections.toml。

  • 安全的 .env 存储：在 macOS/Linux 上为 chmod 0o600（仅所有者可读/写）；在 Windows 上，.env 位于 %APPDATA%，该目录由 Windows ACL 限制为你的用户配置文件。

  • 标识符验证：表/schema/数据库名称在插入 SQL 之前会对照 [A-Za-z0-9_]+ 进行检查。

  • 经过测试：tests/test_readonly.py 中有 40 多个单元测试，覆盖每个写关键字、注释剥离边界情况、带写操作的 CTE 尝试、分号分隔的多语句以及标识符注入尝试。运行 pytest tests/test_readonly.py 可在你的机器上验证。

这对我的数据安全吗？

amnesic 仅限本地且仅限协议层面。它不会引入新的外部信任边界——信任边界在于你的 MCP 客户端将数据发送到哪里，而不是 amnesic 本身。 选择 AI 客户端就决定了适用于你的数据的策略。

your DB → amnesic (local) → MCP client → your AI deployment
                                          ↑ trust boundary lives here

无论你是独立开发者还是企业用户，需要诚实面对的问题是：

我是否信任我的 AI 客户端处理此数据库中的数据？

如果信任——对于大多数配置来说，答案是肯定的——那就没问题。这包括：

  • 使用 Claude Pro / Cursor / Copilot 处理自己项目、开发数据库或测试数据的独立开发者

  • 查询个人 SQLite 或自托管 Postgres 的副业项目

  • 处理公共 schema 的开源维护者

  • 使用具有明确隔离的企业 AI 的团队：AWS Bedrock（租户 + IAM）、Azure OpenAI（区域固定，你的订阅）、Anthropic Enterprise（零数据保留，训练退出）、Vertex AI（你的 GCP 项目）、自托管（Ollama、vLLM、本地 Claude/GPT——数据永不离开网络）

  • 任何使用具有零保留保证和涵盖你用途的 DPA 的付费 AI 计划的用户

如果以下情况，值得仔细审视

  • 你的数据库包含属于他人的数据（用户、客户、患者），且你尚未验证你的 AI 提供商的条款是否涵盖该处理

  • 你使用的是消费级 AI（免费/个人 Pro）并且处理受监管数据——PHI（HIPAA 覆盖实体）、持卡人数据（PCI-DSS）、GDPR / 印度 DPDP 法案下的受限 PII

  • 你的雇主有明确政策限制在生产数据库上使用外部 AI 工具

  • 你受数据驻留规则约束，行数据不能离开特定区域

数据最小化是内置的

这是设计的一个属性，而非事后考虑：注解层意味着 AI 可以从本地 SQLite 知识文件回答大多数 schema 问题——无需运行 db_query，不会将任何行数据发送到任何地方。

  • "status=3 是什么意思？" → 从你保存的注解中解析

  • "orders 如何与 users 连接？" → 从外键图中解析

  • "哪些表有 created_at 列？" → 从 schema 缓存中解析

对于纯结构探索，有六个工具永远不会触及你的数据：db_list_tables、db_get_schema、db_search、db_annotate、db_discover_relationships、db_get_relationships。它们只返回元数据。

这比"裸"SQL MCP 的数据移动量可衡量地更少——后者每次 AI 对枚举感到困惑时都必须运行 SELECT DISTINCT status FROM orders。amnesic 只需从本地注解中回答一次。

免责声明：amnesic 按 MIT 许可证按"原样"提供（无担保，无责任——参见 LICENSE）。本节内容不构成法律或合规建议。你使用 amnesic 以及你连接它的 AI 客户端的责任由你自己承担。如果你处理受监管数据，请在将其指向生产环境之前咨询你的安全/合规团队。

路线图

目前已发布：知识层（v0.1）、BM25 搜索（v0.1.5）、生命周期管理——弃用/漂移检测/遗忘（v0.2），以及可移植知识导出/导入（v0.2.2）。

下一步（v0.3——"赢得记忆"）： 无需任何人输入即可积累的知识——枚举自动发现、针对无约束的遗留 schema 的软外键推断，以及 JOIN 模式学习。此外还有基础性工作：每个响应的 token 预算、schema 获取中的索引和主键、缓存过期标志，以及更精简的工具面。

完整路线图及排序背后的理由，请参阅 ROADMAP.md。

🙌 欢迎贡献

v0.3 的每一项都已作为 GitHub issue 提交，且设计已经过深思熟虑——包括问题、拟议形态、需要改动的文件以及如何测试。其中几项已标记为 good first issue。

挑一个并提交 PR——无需事先询问。只需在 issue 下留言，以免两个人做同一件事。

有未列出的想法？打开一个 issue。 用例胜过补丁——它能避免你返工。

使用情况追踪

pypistats.org/packages/amnesic

许可证

MIT——参见 LICENSE。

MCP 注册表

此服务器已注册到官方 MCP 注册表。

mcp-name: io.github.SurajKGoyal/amnesic

Available Tools

12 tools
db_annotateA
Persist semantic annotations for a table or column — survives across sessions.

This is the core of amnesic's persistent memory. Every annotation saved here
is automatically merged into future db_get_schema() responses, so the AI
never has to rediscover what a status code means or what a table is for.

Call this after discovering: what an enum value means, what a column represents,
how a table relates to another, or what a table is used for.

Args:
    table:              Table name, optionally schema-qualified to match your
                        DB — e.g. "users", "public.users" (Postgres),
                        "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:         Connection name. Defaults to first defined.
    table_description:  Human-readable description of the table's purpose.
    table_aliases:      Alternative names the table is known by.
    column:             Column to annotate (required for column-level args below).
    column_description: What this column represents in the business domain.
    enum_values:        Dict mapping stored values to labels {"1": "active", "2": "inactive"}.
    foreign_key:        FK reference as "other_table.column_name".
    example_values:     Representative sample values from this column.

Returns:
    {table, connection, updated: {table_knowledge?, column_knowledge?}}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
table_descriptionNo
table_aliasesNo
columnNo
column_descriptionNo
enum_valuesNo
foreign_keyNo
example_valuesNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must fully disclose behavior. It states annotations survive sessions, are merged into future db_get_schema responses, and calls it the core of persistent memory. This effectively communicates the mutating and persistent nature. It doesn't discuss permissions or reversibility, but given the positive intent (annotating for better future queries), the transparency is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a brief summary, contextual motivation, usage guidance, parameter list, and return type. Every sentence adds value, and the length is appropriate for the tool's complexity. There is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 9 parameters and no annotations or output schema, the description covers the tool's purpose, when to use it, parameter semantics, and return format. It also explains how it integrates with db_get_schema, providing sufficient context for an AI agent to use it correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% coverage (no descriptions), so the description must compensate. The Args section provides clear semantic explanations for each parameter, including schema qualification for table, relationship between column and column-level fields, and the dict format for enum_values. This adds significant meaning beyond the raw schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool persists semantic annotations for tables or columns, surviving across sessions. It distinguishes from siblings by positioning itself as the persistent memory mechanism that feeds into db_get_schema, a unique role not covered by other sibling tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly advises calling this tool after discovering semantic knowledge (enum meanings, column purposes, relationships). While it doesn't list when to avoid it or name alternatives, the context and sibling list imply when to use versus when to use other tools like db_get_schema or db_query.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_deprecateA
Soft-retire a table or column annotation — flag it stale without deleting it.

Use when a table/column still exists but should no longer be relied on. The
deprecation flag is surfaced in db_get_schema so the AI is warned off it on
future calls. Reversible via undo=True. To remove an annotation entirely
(e.g. the column was dropped from the DB), use db_forget instead.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column to deprecate. Omit to deprecate the whole table.
    reason:     Why it's deprecated (e.g. "replaced by status_v2").
    undo:       Clear the deprecation flag instead of setting it.

Returns:
    {table, connection, column, target, deprecated, reason}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
reasonNo
undoNo

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, but description explains the deprecation flag is surfaced in db_get_schema and that operation is reversible. Lacks details on permissions or side effects, but sufficient for a soft-retire tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with summary, usage guidelines, and argument list. Slightly wordy but each sentence adds value. No redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 5 parameters, no output schema, and no annotations, the description covers all inputs, explains return format, and mentions interaction with db_get_schema. Distinguishes from sibling db_forget.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but description provides full argument list with detailed explanations, defaults, and usage nuances (e.g., connection defaults to first defined, column omitted means whole table).

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool soft-retires a table or column annotation, distinguishing it from db_forget which removes entirely. Specific verb+resource combination.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use (table/column still exists, should not be relied on) and when not (use db_forget instead). Also mentions reversibility via undo=True.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_detect_driftA
Audit saved annotations against the live database schema (read-only).

Surfaces drift after the schema evolves:
  - orphaned annotations — a table or column you annotated that no longer
    exists in the DB. Remove with db_forget, or db_deprecate if pending.
  - undocumented tables — live tables with no annotation yet (coverage gaps).

Changes nothing — purely a report. Run after schema changes, or periodically.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, orphaned_tables, orphaned_columns, undocumented_tables,
     undocumented_truncated, summary}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description explicitly states the tool is read-only ('Changes nothing — purely a report.') and details what it surfaces (orphaned annotations, undocumented tables). It also outlines the return structure (connection, orphaned_tables, etc.), providing full transparency without relying on annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: it opens with a clear verb-resource statement, uses bullet points for key outputs, and includes a separate Args/Returns section. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having only one optional parameter and no output schema, the description fully covers the tool's function, when to use it, what it detects, and the format of its return. No gaps remain for the intended use case.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only has one parameter (connection) with default null. The description adds meaning by stating 'Defaults to first defined,' which goes beyond the schema's default value. Given the parameter's simplicity, the description provides sufficient context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Audit saved annotations against the live database schema (read-only).' It specifies the verb (audit) and the resource (annotations vs live schema), and distinguishes itself from sibling tools like db_forget and db_deprecate by emphasizing it is a read-only report that detects drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Run after schema changes, or periodically.' It also advises on follow-up actions ('Remove with db_forget, or db_deprecate if pending.'), making the usage context clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_discover_relationshipsA
Discover all foreign key relationships in the database and save them to the graph.

Runs driver-specific FK introspection queries against the live database and
persists results to the local KnowledgeStore. Run once per database; re-run
after schema changes. After discovery, use db_get_relationships to navigate
the graph when planning complex JOIN queries.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, discovered: count, relationships: [{from_table, from_column, to_table, to_column}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: runs driver-specific FK introspection queries, persists to KnowledgeStore, and implies potential impacts (live database query). Could mention performance implications or permissions, but still transparent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a short summary, usage guidelines, and listed args/returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Completely covers the tool's lifecycle, return format, and relationship to sibling tools. No gaps given the simple parameter set and no output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description includes an Args section explaining the single parameter 'connection', its meaning, and default behavior ('Defaults to first defined'), adding value beyond the schema which only shows default null.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool discovers all foreign key relationships and saves them to the graph. It uses specific verbs (discover, save) and resources (foreign key relationships, database, graph), and distinguishes from sibling tool db_get_relationships.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use ('Run once per database; re-run after schema changes') and when not, by directing to use db_get_relationships for navigation after discovery.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_forgetA
Permanently delete a table or column annotation. Safe by default — NOT reversible.

Use to remove a wrong annotation, or to clean up after a table/column was
dropped from the DB (pairs with db_detect_drift). Unlike db_deprecate, this
hard-deletes. Cascade is opt-in so you can't nuke a table by accident:
  - db_forget(table)               -> ONLY the table's own annotation
  - db_forget(table, column="x")   -> ONLY that column's annotation
  - db_forget(table, cascade=True) -> the table + all its column annotations
                                      + all relationships touching it

Only the local knowledge store is changed — never the live database.

Args:
    table:      Table name, optionally schema-qualified (e.g. "users",
                "public.users", "dbo.Orders", "mydb.orders").
    connection: Connection name. Defaults to first defined.
    column:     Column annotation to delete. Omit to target the table.
    cascade:    When targeting a table, also delete its columns +
                relationships. Ignored when column is given.

Returns:
    {table, connection, column, removed_table, removed_columns, removed_relationships}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
columnNo
cascadeNo

TDQS

A5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully discloses behavior. It states 'Safe by default — NOT reversible,' explains cascade behavior, and clarifies that only the local knowledge store is changed, never the live database.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with bullet points and examples. Every sentence adds value, and critical information is front-loaded immediately after the first line.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains the return object structure. It covers all necessary context: irreversibility, local-only modification, cascade behavior, and relation to siblings. Complete for a destructive knowledge store tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description provides detailed semantics for all 4 parameters: table examples, connection default, column omit behavior, cascade ignored when column given. This adds significant value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Permanently delete a table or column annotation.' It uses specific verbs and resources, and explicitly distinguishes from siblings like db_deprecate (soft-delete) and pairs with db_detect_drift.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to use: 'Use to remove a wrong annotation, or to clean up after a table/column was dropped from the DB.' Provides when-not guidance by contrasting with db_deprecate, and explains cascade opt-in to prevent accidents.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_relationshipsA
Get the foreign key relationship graph for a table up to the given traversal depth.

Depth 1 returns direct neighbors (tables one JOIN away). Depth 2 returns
neighbors-of-neighbors. Returns both a flat neighbor list and formatted join
path strings to help plan multi-table queries. Requires db_discover_relationships
to have been run first.

Args:
    table:      Table name (e.g. "Orders").
    connection: Connection name. Defaults to first defined.
    depth:      BFS traversal depth (default 1, recommended max 3).

Returns:
    {table, connection, neighbors: [...], paths: ["TableA -> TableB -> TableC", ...]}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
depthNo

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the output format (neighbor list and join paths) and the prerequisite step. As no annotations are provided, the description carries full burden; it lacks explicit mention of side effects or idempotency but is sufficient for understanding behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections for Args and Returns. It is concise without unnecessary words, front-loading the primary purpose and then detailing parameters and output.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and no annotations, the description is comprehensive: it explains the output structure, prerequisite, and each parameter fully. An agent can correctly invoke this tool based solely on the description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by explaining all three parameters, their purposes, defaults, and even a recommended maximum depth for depth. This provides complete semantic understanding.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: retrieving the foreign key relationship graph for a table up to a given depth. It distinguishes itself from sibling tools by explicitly requiring db_discover_relationships to have been run first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage context: it explains depth levels and that the prerequisite tool must be run first. However, it does not explicitly state when not to use this tool or mention alternatives beyond the prerequisite.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_get_schemaA
Get column schema for a table, merged with any saved semantic annotations.

Checks the local cache first; fetches from the database on cache miss or
when force_refresh=True. Saves the result to cache for future calls.
Merges column descriptions, enum value mappings, and FK references from
previous db_annotate() calls into the response.

Args:
    table:         Table name, optionally schema-qualified. Use whatever your
                   DB uses — e.g. "users", "public.users" (Postgres),
                   "dbo.Orders" (MSSQL), "mydb.orders" (MySQL).
    connection:    Connection name. Defaults to first defined.
    force_refresh: Bypass cache and fetch fresh schema from the database.

Returns:
    {table, connection, columns (with annotations merged in), table_description, cached}
ParametersJSON Schema
NameRequiredDescriptionDefault
tableYes
connectionNo
force_refreshNo

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Given no annotations, the description fully discloses caching behavior, force refresh mechanism, and annotation merging, providing complete behavioral transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, front-loaded with the purpose, and every subsequent sentence adds necessary detail without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite lacking output schema, the description covers all essential aspects: purpose, caching, param details, and return structure, making it complete for a 3-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema coverage, the description thoroughly explains each parameter: table with DB-specific examples, connection with default, and force_refresh with functionality, adding significant value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves column schema merged with semantic annotations, distinguishing it from sibling tools like db_annotate (which adds annotations) and db_list_tables (which lists tables).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides context on when to use (to get annotated schema) and parameter usage, but lacks explicit guidance on when not to use or alternatives to sibling tools, which would improve clarity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_connectionsA
List all configured database connections without exposing passwords or usernames.

Use this first to see what databases are available before calling other tools.
Returns connection names, drivers, databases, and server addresses.

Returns:
    {connections: [{name, driver, database, server}]}
ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that passwords and usernames are not exposed, which is a key behavioral trait. However, does not explicitly state read-only nature or any side effects, though implied for a list operation. No annotations to contradict or supplement.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: two sentences plus a returns block. Front-loaded with main purpose. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Fully explains what the tool does and what it returns (list of connections with name, driver, database, server). No missing info given the simplicity of the tool and absence of parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so baseline is 4. Description does not need to add parameter info. Schema coverage is 100% by default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states listing all configured database connections without exposing sensitive info. Differentiates from siblings like db_list_tables by specifying the resource (connections). Uses specific verb 'list' and describes return fields.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises to use this tool first before other tools to see available databases. Provides a clear usage context and sequential guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_list_tablesA
List all known tables for a connection, with descriptions and column counts.

Tables appear once they have been fetched via db_get_schema or annotated via
db_annotate. Descriptions come from the knowledge store — richer than raw
INFORMATION_SCHEMA.

Args:
    connection: Connection name. Defaults to first defined.

Returns:
    {connection, database, tables: [{table_fqn, description, aliases, column_count}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
connectionNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It discloses that descriptions come from the knowledge store (richer than raw schema) and that tables are only shown if known. No destructive behavior implied. Return format is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with clear purpose, behavioral notes, Args, and Returns. Every sentence adds value, no fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, no output schema), the description covers all essential aspects: purpose, prerequisites, return format, and parameter behavior. Complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Single optional parameter 'connection' is documented with default behavior ('Defaults to first defined'), adding useful meaning beyond the schema type and default.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it lists all known tables for a connection, including descriptions and column counts. It distinguishes itself from siblings like db_get_schema (which fetches schema) and db_annotate (which annotates) by noting that tables appear only after those actions.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context by explaining that tables appear only after being fetched or annotated, guiding the user on prerequisites. However, it does not explicitly state when to use or not use this tool versus alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_queryA
Execute a read-only SELECT query and return rows as a list of dicts.

All queries run inside an immediately-rolled-back transaction — write
statements are blocked both statically and at the transaction level.
Call db_get_schema first if you are unfamiliar with the table structure.

Args:
    sql:        SELECT query to execute. No INSERT/UPDATE/DELETE allowed.
    connection: Connection name (e.g. "orders.prod"). Defaults to first defined.
    max_rows:   Maximum rows to return (default 500). Set lower for large tables.

Returns:
    {rows, row_count, connection, database, truncated}
ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYes
connectionNo
max_rowsNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses that queries run in an immediately-rolled-back transaction and that write statements are blocked both statically and at the transaction level. It also outlines the return structure (rows, row_count, connection, database, truncated). Since no annotations are provided, the description carries the full burden and does so well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: a single sentence stating the core purpose, followed by a brief note on transaction behavior and a recommendation to use a sibling tool, then a bullet-style summary of parameters and return value. No superfluous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (3 parameters, no output schema), the description covers the main behavioral aspects (transaction, write blocking), parameter semantics, and return format. It could optionally mention error handling or performance implications, but overall it is sufficiently complete for an AI agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description provides comprehensive meaning for all three parameters: sql (SELECT-only), connection (defaults to first defined), and max_rows (default 500, lower for large tables). This goes far beyond the bare schema, which only supplies names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a read-only SELECT query and returns rows as a list of dicts. It specifies that write statements are blocked, making the purpose unambiguous. Although not explicitly compared to siblings, the verb-resource combination ('Execute a read-only SELECT query') is specific and distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description advises to call db_get_schema first if unfamiliar with the table structure, providing a clear alternative. It also implicitly limits usage to read-only queries (SELECT only) and mentions max_rows for large tables. However, it does not explicitly exclude other query types or describe when not to use the tool beyond the SELECT constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

db_sync_knowledgeA
Copy annotations from one connection's knowledge store to another.

Typical use: after confirming that staging and prod share the same schema,
sync all the semantic knowledge you've built up in staging to prod.
Only syncs tables and columns that exist in the target schema cache —
tables missing from target are reported in 'skipped', columns in 'warnings'.

Args:
    from_connection: Source connection (e.g. "orders.staging").
    to_connection:   Target connection (e.g. "orders.prod").
    tables:          Optional list of specific table FQNs to sync. Defaults to all.

Returns:
    {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}
ParametersJSON Schema
NameRequiredDescriptionDefault
from_connectionYes
to_connectionYes
tablesNo

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description fully bears the transparency burden. It discloses that only tables/columns existing in target are synced, with skipped and warnings reported. It also describes the return structure in detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured with a typical use case, behavior explanation, and clear Args/Returns sections. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no output schema, and no annotations, the description is highly complete. It covers the sync process, edge cases (missing items), and return format, leaving no critical gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning by explaining 'from_connection' and 'to_connection' as source/target with example values ('orders.staging', 'orders.prod'), and 'tables' as an optional list of FQNs defaulting to all. This provides clarity beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool copies annotations between knowledge stores. It uses a specific verb 'sync' and resource 'annotations from knowledge store', distinguishing it from sibling tools like db_annotate or db_query.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It provides a typical use case: syncing from staging to prod after confirming schema match. It also explains behavior for missing tables/columns. However, it does not explicitly exclude other scenarios or mention alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 12 tool updatesv0.2.2
    • First observeddb_annotate
    • First observeddb_deprecate
    • First observeddb_detect_drift
    • First observeddb_discover_relationships
    • First observeddb_forget
    • First observeddb_get_relationships
    • First observeddb_get_schema
    • First observeddb_list_connections
    • First observeddb_list_tables
    • First observeddb_query
    • First observeddb_search
    • First observeddb_sync_knowledge
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

Each tool has a clear, distinct purpose. There is no overlap: annotation management (annotate, deprecate, forget), schema retrieval (get_schema, list_tables), querying (query), searching (search), relationship discovery (discover_relationships, get_relationships), drift detection (detect_drift), and knowledge sync (sync_knowledge) are all separate concerns.

Naming Consistency5/5

All tools follow the consistent pattern `db_<verb>_<noun>` using snake_case. The verbs are descriptive and indicate the action (e.g., annotate, query, list_tables). No mixing of conventions or vague names.

Tool Count5/5

With 12 tools, the server is well-scoped for a database knowledge management system. Each tool serves a necessary function in the lifecycle of schema understanding, annotation, querying, and maintenance. Not overloaded nor sparse.

Completeness4/5

The tool set covers the core workflow: connection listing, table discovery, schema retrieval, querying, annotation CRUD (annotate, deprecate, forget), relationship discovery, drift detection, and knowledge sync. Missing a direct tool to view all annotations in isolation, but schema retrieval and search provide access.

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SurajKGoyal/amnesic'

If you have feedback or need assistance with the MCP directory API, please join our Discord server