Skip to main content
Glama
deenesjakoruzh
SurajKGoyal

amnesic

by SurajKGoyal
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

amnesic — the MCP server with the most ironic name in the registry

PyPI version Python License: MIT MCP Registry Glama score

Your database's institutional memory, as an MCP server. The name is ironic — it remembers everything.

"The MCP server with the most ironic name in the registry. It's anything but amnesic — it remembers your database so your AI doesn't have to."

Most database MCP servers are query executors: they connect, introspect, run SQL, and forget. amnesic is a semantic memory — it accumulates what your schema means (what status = 3 is, which columns are really foreign keys, what that legacy table is for) and hands it to every future session automatically. Think data catalog, minus the platform, the ingestion pipeline, and the invoice. Where amnesic fits ↓

Works with Claude Code · Claude Desktop · Cursor · VS Code · Cline · Windsurf — any MCP-compatible client.

Available on Official MCP Registry · Claude Code plugin marketplace

👋 Using amnesic? Say hi in the adopters thread — download counts can't tell me what's actually being used, and it directly shapes what gets built next.

🔒 Read-only by design. amnesic refuses to execute INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, MERGE, GRANT, REVOKE — and any write statement smuggled inside a WITH CTE. Two layers of defense: static SQL analysis rejects the statement before connecting, and every query runs inside a transaction that is immediately rolled back. Safe to point at prod. Details ↓

The problem

Every session with an AI starts cold. You spend the first few minutes re-explaining what tables exist, what a status column value of 3 means, which FK connects orders to users. Then the session ends, and you do it all over again tomorrow.

amnesic fixes this. It gives your AI a persistent SQLite knowledge store — one per database — that survives across sessions. Annotate a status enum once; every future session sees those labels automatically. Discover FK relationships once; every future JOIN query uses that graph.

The knowledge is also portable and outlives your access to the database. When you rotate off a project, amnesic export hands the next developer everything you taught it — years of "oh, that column actually means…" that would otherwise leave with you.

Related MCP server: engram-mcp

Where amnesic fits

The database MCP ecosystem splits into two camps, and amnesic is deliberately in neither.

Query executors — DBHub, Postgres MCP Pro, Google's MCP Toolbox, and the vendor servers (Supabase, Neon). They introspect live, run SQL, and some go deep on performance — Postgres MCP Pro does genuine index tuning and PgHero-style health checks. They are excellent at this. They are also stateless: every session re-learns your schema from scratch, and nothing they return can tell you what a column means, because the database doesn't know either.

Enterprise catalogs — DataHub, Atlan, Cube, AtScale. These do hold semantic context: glossaries, column descriptions, ownership, lineage. They're also a platform commitment — metadata ingestion, a service to run, usually a paid tier. Worth it at company scale; wildly disproportionate for one developer who needs to remember what six status codes mean in a legacy MSSQL database nobody will ever onboard to a catalog.

amnesic is the third thing: catalog-grade semantic memory at query-executor setup cost. pipx install, one TOML file, a local SQLite file per database. No platform, no ingestion, no server to run.

Honest comparison

amnesic

Query executors

Enterprise catalogs

Semantic context (what a value means)

✅ persistent, yours

❌ none

✅ platform-managed

Survives across sessions

✅

❌

✅

Portable / outlives DB access

✅ export/import

❌

⚠️ platform-bound

Setup cost

one command

one command

ingestion pipeline

Live schema freshness

⚠️ cached, manual refresh

✅ always live

⚠️ ingestion lag

Execution plans / index tuning

❌

✅ (Postgres MCP Pro)

❌

Lineage / ownership / governance

❌

❌

✅

Works on legacy schemas with no FK constraints

✅ annotate them yourself

❌ nothing to introspect

⚠️ needs ingestion

Use a query executor instead of amnesic if you want execution plans, index recommendations, or database health diagnostics — that's not amnesic's job and adding it would make it a worse version of a tool that already exists.

Use amnesic alongside one. They compose: nothing stops you running both. amnesic holds the meaning; they hold the machinery.

The rows marked ⚠️ above are known gaps with open issues — see Roadmap ↓.

Quickstart (90 seconds)

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

⚡ Try it without credentials. Run amnesic init --demo instead — it adds a self-contained SQLite sample DB (e-commerce schema: customers / products / orders with FKs and an enum column) so you can exercise every tool in under a minute. Great for a first look before pointing amnesic at a real database.

The wizard asks which database type you're connecting to and tells you the one command to run if its driver isn't installed yet — you never need to guess extras up front.

The wizard:

  • Asks for your database type, host, and credentials

  • Tests the connection before saving anything

  • Stores the password securely in ~/.config/amnesic/.env (chmod 600)

  • Writes the connection block to ~/.config/amnesic/connections.toml

Then add amnesic to your AI client and restart.

Install pipx (one-time):

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

Or use uv (single-binary alternative — fast, no Python required):

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

Or plain pip (installs into your active Python env):

pip install amnesic

Whichever you pick, amnesic init asks which database you'll connect to and prints the one extra command to install that driver — no need to commit to extras up front.

After install, amnesic --help works from any terminal.

Where amnesic stores things

File

macOS / Linux

Windows

Config

~/.config/amnesic/connections.toml

%APPDATA%\amnesic\connections.toml

Secrets

~/.config/amnesic/.env (chmod 600)

%APPDATA%\amnesic\.env (user profile ACL)

Knowledge

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

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

Set $AMNESIC_HOME (or $XDG_CONFIG_HOME on Linux) to override the location.

Adding more connections later

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

Setting and rotating passwords

amnesic init and amnesic add save your password automatically — for the typical setup flow, you never need to think about this section.

Use set-secret when you need to change a stored password later — IT rotated it, you mistyped it during setup, or you're hand-editing the config.

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

What's the variable name? It's the env var your connections.toml references for that connection's password. The wizard auto-generates these as <CONNECTION_NAME_UPPERCASE_WITH_UNDERSCORES>_PASSWORD:

Connection name

Generated env var

orders.prod

ORDERS_PROD_PASSWORD

analytics

ANALYTICS_PASSWORD

drive.staging

DRIVE_STAGING_PASSWORD

To see the exact name your config uses, check ~/.config/amnesic/connections.toml — anything inside ${...} is the variable to pass to set-secret.

Under the hood: writes (or replaces) the line in ~/.config/amnesic/.env, sets file permission to chmod 600 (only your user can read it), preserves all other entries.

Managing connections and knowledge

Knowledge accumulates per connection in a local SQLite file. These commands let you move it between machines and clean up:

# 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 operate purely on local files — they never connect to the database, so they work even if a connection's credentials aren't set. remove edits connections.toml with surgical string edits, leaving every other block's formatting and comments byte-for-byte intact.

Add to your AI client

Once amnesic is installed with the right driver extras (see Quickstart), the amnesic command is on your PATH. Use the same snippet across every MCP client:

Claude Code

One-line install (recommended — no JSON editing). Inside Claude Code:

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

That wires amnesic as an MCP server automatically. Source: SurajKGoyal/amnesic-marketplace.

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

Claude Desktop

Add to your platform's Claude Desktop config:

  • 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

One-click install — click the button below and Cursor wires it up for you:

Add to .cursor/mcp.json in your project (or ~/.cursor/mcp.json globally):

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

Without a global install (ephemeral)

If you'd rather not install amnesic on your system, use uvx or pipx to fetch it each time the MCP client starts. Note the driver extras must be passed explicitly:

// 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"]
    }
  }
}

For multiple drivers, comma-separate inside the brackets — e.g. amnesic[postgres,mssql] or use amnesic[all] for everything.

VS Code (with MCP extension)

Add to .vscode/mcp.json:

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

Updating

amnesic ships often. Upgrade with the same tool you installed it with:

Installed via

Upgrade command

pipx

pipx upgrade amnesic

uv tool

uv tool upgrade amnesic

pip

pip install --upgrade amnesic

uvx (ephemeral, in your MCP config)

uvx caches builds — run uv cache clean amnesic to pull the newest

Then restart your MCP client (Claude Code, Cursor, …) so it relaunches the amnesic server and picks up any new tools.

Upgrading is safe — you won't lose annotations. Your knowledge files auto-migrate to the new schema on first load; amnesic only ever adds columns, never drops your data.

To check the installed version: amnesic --version. Latest release: PyPI · Releases.

Tools

Tool

Description

db_list_connections()

List all configured connections (no secrets exposed)

db_list_tables(connection)

All known tables with descriptions and column counts

db_search(query, connection, target, limit)

BM25 search over table/column descriptions and aliases

db_get_schema(table, connection)

Column schema merged with saved annotations

db_query(sql, connection)

Execute a read-only SELECT query

db_annotate(table, connection, ...)

Persist semantic annotations for tables/columns

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

Soft-retire a stale annotation — flagged (and warned) but kept, reversible

db_detect_drift(connection)

Audit annotations vs the live schema — find orphaned annotations + undocumented tables

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

Hard-delete an annotation (cascade opt-in) — permanent

db_sync_knowledge(from, to)

Copy annotations between connections (e.g. staging → prod)

db_discover_relationships(connection)

Discover all FK relationships from the live DB

db_get_relationships(table, connection)

Navigate the FK graph for JOIN planning

Searching the knowledge base

For large schemas, db_list_tables is impractical — you'd dump 500+ rows into Claude's context. Use db_search to find the relevant tables/columns by keyword instead:

"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 uses SQLite FTS5 with BM25 ranking — fast, local, no embeddings or external services. Search syntax supports:

Syntax

Effect

payment

Match the word (with stemming — also matches "payments", "paying")

"payment method"

Exact phrase

pay*

Prefix match — "payment", "payable", etc.

payment AND status

Both terms required

payment OR refund

Either term

Results return ranked table/column rows with descriptions and highlighted snippets.

The knowledge layer

The core differentiator. Every annotation survives restarts, model updates, and new sessions.

Session 1 — you discover something

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.

Session 2 — the knowledge is already there

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 ...

No re-discovery. No wasted turns. The annotation persisted.

Relationship graph

Understand your schema's JOIN structure once, reuse it forever.

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

Now the AI knows exactly how to JOIN across your schema without guessing.

Sync between environments

Build up annotations in staging, then promote to prod:

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

Returns {synced: [...], skipped: [{table, reason}], warnings: [{table, column, reason}]}.

Tables missing from the target schema cache are skipped with a clear reason. Columns missing from target schema are warned but don't block the rest of the sync.

Advanced: hand-edit the TOML

If you prefer to manage the config file yourself, generate a blank template:

amnesic init --template

This writes ~/.config/amnesic/connections.toml with commented examples and exits — no wizard. Edit the file directly:

# ~/.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)

Use ${ENV_VAR} for credentials — never hardcode passwords.

Secrets are loaded from ~/.config/amnesic/.env automatically (format: KEY=VALUE, one per line, # for comments). For each ${VAR_NAME} referenced in your TOML, populate the matching .env entry with amnesic set-secret VAR_NAME (hidden input, chmod 600), or write .env yourself.

Canonical connection names use dot notation: orders.prod, orders.staging, analytics, local.

Supported databases

Database

Python driver

Installed by

PostgreSQL

psycopg2-binary

wizard nudge when you pick Postgres, or amnesic[postgres] extras

MySQL / MariaDB

pymysql

wizard nudge when you pick MySQL, or amnesic[mysql] extras

Microsoft SQL Server

pymssql

wizard nudge when you pick MSSQL, or amnesic[mssql] extras

SQLite

stdlib sqlite3

always available — no extra

Safety & read-only enforcement

amnesic is built to be safe to point at production databases.

Why your AI can't damage your data

Every query passes through two independent layers before reaching the database:

  1. Static analysis (in amnesic/readonly.py) — the SQL is tokenized and rejected if it contains any of: INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, EXEC, EXECUTE, MERGE, BULK, GRANT, REVOKE, DENY. This includes write statements smuggled inside CTEs (WITH x AS (SELECT ...) UPDATE ... is caught and refused).

  2. Transaction rollback — even if a write statement somehow gets past the static check, the query runs inside BEGIN TRANSACTION ... ROLLBACK so nothing is ever committed. Belt and suspenders.

Only SELECT and WITH ... SELECT reach the database. Comments are stripped before analysis so /* DELETE FROM users */ can't be used to hide an attack.

Other safety measures

  • No credentials in responses: db_list_connections strips passwords and usernames from its output. The AI can see which connections exist, never how to authenticate to them.

  • Credentials via env vars only: ${ENV_VAR} expansion at config-load time — passwords never touch connections.toml on disk.

  • Secure .env storage: on macOS/Linux chmod 0o600 (owner read/write only); on Windows the .env lives in %APPDATA% which is restricted to your user profile by Windows ACL.

  • Identifier validation: table/schema/database names are checked against [A-Za-z0-9_]+ before any string interpolation into SQL.

  • Tested: 40+ unit tests in tests/test_readonly.py cover every write keyword, comment-stripping edge case, CTE-with-write attempts, semicolon-separated multi-statements, and identifier injection attempts. pytest tests/test_readonly.py to verify on your machine.

Is this safe with my data?

amnesic is local-only and protocol-only. It doesn't introduce a new external trust boundary — the trust boundary is wherever your MCP client sends data, not amnesic itself. Choosing the AI client decides the policy that applies to your rows.

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

The honest question to ask, whether you're indie or enterprise:

Do I trust my AI client with the data in this database?

If yes — and for most setups, the answer is yes — you're good. That covers:

  • Solo devs on Claude Pro / Cursor / Copilot using their own projects, dev DBs, or test data

  • Side projects querying personal SQLite or self-hosted Postgres

  • Open-source maintainers working with public schemas

  • Teams on enterprise AI with explicit isolation: AWS Bedrock (tenant + IAM), Azure OpenAI (region-pinned, your subscription), Anthropic Enterprise (zero data retention, training opt-out), Vertex AI (your GCP project), self-hosted (Ollama, vLLM, on-prem Claude/GPT — data never leaves the network)

  • Anyone on a paid AI plan with zero-retention guarantees and a DPA covering your use

Worth a closer look if

  • Your DB holds data belonging to other people (users, customers, patients) and you haven't verified your AI provider's terms cover that processing

  • You're on consumer-tier AI (free / personal Pro) AND working with regulated data — PHI (HIPAA covered entity), cardholder data (PCI-DSS), restricted PII under GDPR / India's DPDP Act

  • Your employer has an explicit policy restricting external AI tool use on prod DBs

  • You're under data-residency rules where rows can't leave a specific region

Data minimization is built in

A property of the design, not an afterthought: the annotation layer means the AI answers most schema questions from a local SQLite knowledge file — no db_query runs, no row data is sent anywhere.

  • "What does status=3 mean?" → resolves from your saved annotation

  • "How do orders join users?" → resolves from the FK graph

  • "Which tables have a created_at column?" → resolves from schema cache

For purely structural exploration, six tools never touch your data: db_list_tables, db_get_schema, db_search, db_annotate, db_discover_relationships, db_get_relationships. They return metadata only.

That's measurably less data movement than a "naked" SQL MCP — which has to run SELECT DISTINCT status FROM orders every time the AI is confused about an enum. amnesic answers it once from local annotations.

Disclaimer: amnesic is provided as-is under the MIT License (no warranty, no liability — see LICENSE). This section is not legal or compliance advice. Your use of amnesic, and the AI client you connect it to, is your responsibility. If you handle regulated data, consult your security / compliance team before pointing it at production.

Roadmap

Shipped so far: the knowledge layer (v0.1), BM25 search (v0.1.5), lifecycle management — deprecate / drift detection / forget (v0.2), and portable knowledge export/import (v0.2.2).

Next up (v0.3 — "Earn the memory"): knowledge that accumulates without anyone typing it — enum auto-discovery, soft-FK inference for legacy schemas with no constraints, and JOIN-pattern learning. Plus the table-stakes work: a token budget on every response, indexes and primary keys in the schema fetch, cache staleness flags, and a smaller tool surface.

See ROADMAP.md for the full picture and the reasoning behind the ordering.

🙌 Contributions wanted

Every v0.3 item is filed as a GitHub issue with the design already thought through — the problem, the proposed shape, the files to touch, and how to test it. Several are tagged good first issue.

Pick one and open a PR — no need to ask first. Just comment on the issue so two people don't build the same thing.

Have an idea that isn't listed? Open an issue. A use case beats a patch — it saves you rework.

Track usage

pypistats.org/packages/amnesic

License

MIT — see LICENSE.

MCP Registry

This server is registered on the official MCP Registry.

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