@yugabytedb/meko-mcp 1.0.3

package/assets/skills/meko-mcp-tools/references/tools-overview.md

@@ -0,0 +1,97 @@
+# Complete Tool Catalog and Decision Tree
+
+## Quick health check before using tools
+
+Before starting a session, verify that the Meko MCP tools are working:
+
+1. `db_summarize_database(scope="read")` — Confirms DB connection is working. Also doubles as the `agent_id` discovery step (see the main SKILL.md) — look for `<x>_mem0_collection` tables with rows.
+2. `memory_search(scope="read", query="test", agent_id="<discovered>")` — Confirms memory subsystem is up. Substitute the `agent_id` you found in step 1. May fail with "connection already closed" — see `tools-troubleshooting.md`.
+3. `datapack_list(scope="read")` — Confirms Meko API connectivity
+
+If memory tools fail but DB tools work, you can read memory data directly:
+```
+db_run_read_only_query(scope="read", query="SELECT id, payload FROM default_mem0_collection LIMIT 20")
+```
+
+## Decision tree: which tool do I need?
+
+```
+User wants to...
+├── Query or explore the database?
+│   ├── See what tables exist? ---------> db_summarize_database (read)
+│   ├── Run a SELECT / read query? -----> db_run_read_only_query (read)
+│   └── INSERT / UPDATE / DELETE? -------> db_run_write_query (write)
+├── Build or check a knowledge base (RAG)?
+│   ├── Create a new index from sources? -> knowledgebase_trigger_index_creation (write)
+│   ├── Add source to existing index? ---> knowledgebase_add_source_to_index (write)
+│   └── Check build progress? -----------> knowledgebase_check_index_status (read)
+├── Store or recall information?
+│   ├── Store a fact/preference/entity? -----------> memory_add (write)
+│   ├── Store a full conversation (multi-turn)? ---> conversation_create + conversation_add_message (write)
+│   ├── Search past knowledge? --------------------> memory_search (read)
+│   └── Retrieve a past conversation? -------------> conversation_get (read)
+└── Manage datapacks?
+    ├── CRUD datapack? -> datapack_create/list/describe/update/delete
+    ├── Manage agents? -> datapack_create_agent/list_agents/delete_agent
+    └── Manage KB sources? -> datapack_add_knowledge_base/list/delete_knowledge_base
+```
+
+## Database Tools (3)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `db_summarize_database(scope, schema="public", datapack_id=None)` | read | List tables with column schemas and row counts |
+| `db_run_read_only_query(scope, query, datapack_id=None)` | read | Run SELECT, returns JSON. Uses `BEGIN READ ONLY` + `ROLLBACK` |
+| `db_run_write_query(scope, query, datapack_id=None)` | write | Execute INSERT/UPDATE/DELETE/CREATE TABLE. Guardrail-validated. Auto-committed |
+
+## RAG / Knowledge Base Tools (3)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `knowledgebase_trigger_index_creation(scope, source_uris, index_name, ai_provider="OPENAI", embedding_model="text-embedding-3-large", embedding_dimensions=1536, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Register sources + init vector index + trigger build |
+| `knowledgebase_add_source_to_index(scope, index_name, source_id, chunk_size=1024, chunk_overlap=256, datapack_id=None)` | write | Add a new source to an existing index |
+| `knowledgebase_check_index_status(scope, index_name, datapack_id=None)` | read | Check build progress via `dist_rag.vector_index_pipeline_details` |
+
+## Memory Tools (7)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `memory_add(scope, text, agent_id, user_id=None, app_id=None, run_id=None, metadata=None, messages=None, datapack_id=None)` | write | Store fact/preference/entity as long-term memory |
+| `memory_search(scope, query, agent_id, user_id=None, limit=10, datapack_id=None)` | read | Semantic search across memories + graph relations |
+| `memory_get_by_id(scope, memory_id, agent_id, datapack_id=None)` | read | Retrieve a single memory by UUID |
+| `memory_get_all(scope, agent_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | read | List all memories for agent |
+| `memory_update(scope, memory_id, text, agent_id, datapack_id=None)` | write | Overwrite memory text |
+| `memory_delete_by_id(scope, memory_id, agent_id, datapack_id=None)` | write | Delete a single memory |
+| `memory_delete_all(scope, agent_id, user_id=None, app_id=None, run_id=None, datapack_id=None)` | admin | Delete all memories for agent (destructive) |
+
+## Conversation Tools (7)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `conversation_create(scope, agent_id, user_id=None, app_id=None, run_id=None, title=None, metadata=None, session_id="")` | write | Create conversation container (Langfuse session) |
+| `conversation_add_message(scope, conversation_id, agent_id, input, output=None, reasoning=None, metadata=None, seed=None, trace_id="")` | write | Add a message turn (Langfuse trace) |
+| `conversation_get(scope, conversation_id, agent_id, include_messages=False, limit=100, offset=0)` | read | Retrieve conversation, optionally with messages |
+| `conversation_list(scope, agent_id, user_id=None, limit=20, offset=0)` | read | List conversations for agent |
+| `conversation_update(scope, conversation_id, agent_id, title=None, metadata=None)` | write | Update title or metadata |
+| `conversation_delete_message(scope, conversation_id, agent_id, trace_id)` | write | Delete a single message |
+| `conversation_delete(scope, conversation_id, agent_id)` | admin | Delete entire conversation (destructive) |
+
+## Datapack Management Tools (11)
+
+| Tool | Scope | Purpose |
+|------|-------|---------|
+| `datapack_create(scope, name)` | write | Create new datapack |
+| `datapack_list(scope)` | read | List all datapacks |
+| `datapack_describe(scope, name, include_status=False)` | read | Describe datapack |
+| `datapack_update(scope, name, connection_string)` | write | Update connection string |
+| `datapack_delete(scope, name)` | admin | Delete datapack (irreversible) |
+| `datapack_create_agent(scope, datapack_name, agent_name, agent_metadata=None)` | write | Create agent in datapack |
+| `datapack_list_agents(scope, datapack_name)` | read | List agents in datapack |
+| `datapack_delete_agent(scope, datapack_name, agent_name)` | admin | Delete agent |
+| `datapack_add_knowledge_base(scope, datapack_name, url)` | write | Add KB source URL |
+| `datapack_list_knowledge_bases(scope, datapack_name)` | read | List KB sources |
+| `datapack_delete_knowledge_base(scope, datapack_name, url)` | admin | Delete KB source |
+
+## Common Parameter Patterns
+
+Every tool accepts `scope` as the first parameter. All DB, RAG, and memory tools accept optional `datapack_id` to target a specific datapack's database. Memory and conversation tools require `agent_id` for namespace isolation (see `tools-agent-id-conventions.md`).

package/assets/skills/meko-mcp-tools/references/tools-rag-workflow.md

@@ -0,0 +1,63 @@
+# End-to-End RAG Pipeline Workflow
+
+**WRONG:** Calling `knowledgebase_check_index_status` before creating the index (returns empty), or `knowledgebase_add_source_to_index` for initial creation (fails — index doesn't exist yet).
+
+## Step 1: Create the index from sources
+
+`knowledgebase_trigger_index_creation` registers sources, initializes the vector index, and triggers the build in one call:
+
+```
+knowledgebase_trigger_index_creation(
+    scope="write",
+    source_uris="s3://my-bucket/docs/,s3://my-bucket/reports/",
+    index_name="company_docs"
+)
+-- Returns: {"source_ids": [...], "index_name": "company_docs", "status": "build_triggered"}
+```
+
+## Step 2: Poll for build completion
+
+```
+knowledgebase_check_index_status(scope="read", index_name="company_docs")
+```
+
+Check `completion_rate_percent` in `pipeline_stats` and `document_status` in `pipeline_details` to know when all documents are fully indexed.
+
+## Step 3: Add more sources later
+
+Once an index exists, use `knowledgebase_add_source_to_index` with a pre-registered `source_id` (UUID, not URI):
+
+```
+knowledgebase_add_source_to_index(scope="write", index_name="company_docs", source_id="new-source-uuid")
+```
+
+## Tool selection guide
+
+| Situation | Tool |
+|-----------|------|
+| First time creating a RAG index | `knowledgebase_trigger_index_creation` |
+| Adding a source to an existing index | `knowledgebase_add_source_to_index` |
+| Checking if build is complete | `knowledgebase_check_index_status` |
+
+## Troubleshooting: Pipeline stuck at INIT
+
+If `knowledgebase_check_index_status` returns empty `pipeline_details` or documents remain at `INIT` status for more than 5 minutes, the build workers have likely stalled.
+
+**Diagnosis:** Query the work queue directly:
+```
+db_run_read_only_query(scope="read",
+    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
+```
+
+Tasks stuck `IN_PROGRESS` with `lease_expires_at` in the past indicate crashed workers. **Stop polling after 3 consecutive no-progress checks** — continued polling wastes context. See `tools-troubleshooting.md` for full recovery strategies.
+
+## Limitations
+
+- There is **no MCP tool to delete** a vector index, remove a source from an index, or reset stuck work queue tasks.
+- There is **no MCP tool to query** a built index — use `db_run_read_only_query` with `dist_rag` SQL functions directly.
+- `knowledgebase_add_source_to_index` has a **known parameter mismatch bug**. Prefer `knowledgebase_trigger_index_creation` with all sources at once.
+- Each `knowledgebase_trigger_index_creation` call creates a new index. **Do not retry on failure** — you'll create duplicates.
+
+## Prerequisite
+
+All RAG tools require the `dist_rag` PostgreSQL extension in the target database. Pass `datapack_id` to all calls when targeting a specific datapack.

package/assets/skills/meko-mcp-tools/references/tools-scope-permissions.md

@@ -0,0 +1,79 @@
+# Scope Permission Hierarchy and Per-Tool Requirements
+
+**WRONG:** `db_run_write_query(scope="read", ...)` → PermissionError: requires 'write' or higher.
+**WRONG:** `memory_delete_all(scope="write", ...)` → PermissionError: requires 'admin'.
+
+## Scope Hierarchy
+
+```
+admin  (level 2)  -- can do everything
+  ↓
+write  (level 1)  -- can read + write, not admin-only
+  ↓
+read   (level 0)  -- can only read
+```
+
+Higher scopes include lower scopes. An unrecognized scope string always fails.
+
+## Per-Tool Requirements
+
+### read scope (12 tools)
+
+| Tool | Group |
+|------|-------|
+| `db_summarize_database` | Database |
+| `db_run_read_only_query` | Database |
+| `knowledgebase_check_index_status` | RAG |
+| `memory_search` | Memory |
+| `memory_get_by_id` | Memory |
+| `memory_get_all` | Memory |
+| `conversation_get` | Conversation |
+| `conversation_list` | Conversation |
+| `datapack_list` | Datapack |
+| `datapack_describe` | Datapack |
+| `datapack_list_agents` | Datapack |
+| `datapack_list_knowledge_bases` | Datapack |
+
+### write scope (14 tools)
+
+| Tool | Group |
+|------|-------|
+| `db_run_write_query` | Database |
+| `knowledgebase_trigger_index_creation` | RAG |
+| `knowledgebase_add_source_to_index` | RAG |
+| `memory_add` | Memory |
+| `memory_update` | Memory |
+| `memory_delete_by_id` | Memory |
+| `conversation_create` | Conversation |
+| `conversation_add_message` | Conversation |
+| `conversation_update` | Conversation |
+| `conversation_delete_message` | Conversation |
+| `datapack_create` | Datapack |
+| `datapack_update` | Datapack |
+| `datapack_create_agent` | Datapack |
+| `datapack_add_knowledge_base` | Datapack |
+
+### admin scope (5 tools — destructive, irreversible)
+
+| Tool | Group |
+|------|-------|
+| `memory_delete_all` | Memory |
+| `conversation_delete` | Conversation |
+| `datapack_delete` | Datapack |
+| `datapack_delete_agent` | Datapack |
+| `datapack_delete_knowledge_base` | Datapack |
+
+## Best Practices
+
+1. **Use the minimum scope needed.** `scope="read"` for reads documents intent and prevents accidental writes.
+2. **The scope is a parameter, not an auth token.** When OAuth is enabled, the actual permission check happens against the OAuth token's claims. Both `scope` parameter and OAuth permissions must be satisfied.
+
+## Common Mistakes
+
+**WRONG:** `scope="all"` — there is no "all" scope. Valid values are exactly: `"read"`, `"write"`, `"admin"`. Nothing else.
+
+Other invalid values that will fail: `"readwrite"`, `"rw"`, `"full"`, `"any"`.
+
+The error `Insufficient scope: 'all'. This tool requires 'read' or higher.` means the scope string was not recognized as a valid value. Always use one of the three valid strings.
+
+**Default choice:** Start with `scope="read"` unless you specifically need to write or delete.

package/assets/skills/meko-mcp-tools/references/tools-troubleshooting.md

@@ -0,0 +1,143 @@
+# Troubleshooting — Error Recovery and Retry Strategies
+
+These patterns are extracted from real agent sessions. Follow them to avoid wasting tool calls and context window on repeated failures.
+
+## General rules
+
+1. **Never retry the identical failed call more than once.** If it fails twice with the same error, it's not transient — diagnose the cause.
+2. **Distinguish transient vs persistent failures.** "Connection already closed" is transient (retry once). "Permission denied" is persistent (stop, don't retry).
+3. **Don't guess parameters sequentially.** If a tool fails with one parameter format, don't try 4 variations. Check this skill's docs for the correct format first.
+4. **Cache what you learn within a session.** Once you've discovered the user's `agent_id` via `db_summarize_database` (see the main SKILL.md), reuse it for every subsequent call in this session. Re-run discovery on the next session.
+
+---
+
+## Connection errors: "connection already closed"
+
+**Affects:** Memory tools (`memory_add`, `memory_search`, `memory_get_all`) most frequently. DB tools less often.
+
+**Why it happens:** The Python memory subsystem uses a connection cache that doesn't recover from dropped connections (unlike the Go API server which has retry logic with 5 retries and 3-second delays).
+
+**What to do:**
+
+1. Retry the same call **once**
+2. If it fails again, the memory subsystem is unhealthy for this session
+3. Fall back to direct SQL to read memory data:
+   ```
+   db_run_read_only_query(scope="read",
+       query="SELECT id, payload FROM default_mem0_collection LIMIT 20")
+   ```
+   Replace `default` with your `agent_id` prefix if using a custom agent.
+
+**Anti-pattern from real sessions:** Agent called `memory_add` with 500+ tokens of text, got "connection already closed", retried the identical call 3 more times (each 500+ tokens). Wasted ~2000 tokens on guaranteed failures.
+
+---
+
+## RAG pipeline stuck at INIT
+
+**Affects:** `knowledgebase_trigger_index_creation` — the build triggers but never completes.
+
+**Symptoms:**
+- `knowledgebase_check_index_status` returns empty `pipeline_details` and `pipeline_stats`
+- Documents remain at `INIT` status indefinitely
+- Work queue tasks are `IN_PROGRESS` with `lease_expires_at` in the past
+
+**Diagnosis:** Query the work queue directly:
+```
+db_run_read_only_query(scope="read",
+    query="SELECT task_type, status, lease_expires_at FROM dist_rag.work_queue WHERE index_name = 'your_index' ORDER BY created_at DESC LIMIT 10")
+```
+
+Look for tasks stuck `IN_PROGRESS` with expired leases — these indicate crashed or hung workers.
+
+**What to do:**
+
+1. Poll status **at most 3 times** with 1-2 minute intervals
+2. If no progress after 3 checks, **stop polling** — the pipeline is stuck
+3. There is **no way to reset or retry stuck tasks via MCP tools**
+4. Creating a new index with a different name (e.g., `_v2`) is a workaround, but if the workers themselves are down, this will also get stuck
+5. Recommend the user check worker logs or restart the pipeline service
+
+**Anti-pattern from real sessions:** Agent created indexes `v1`, `v2`, `v3` — all stuck with the same symptoms. Even making the S3 bucket public didn't help. The issue was worker infrastructure, not permissions.
+
+---
+
+## db_run_write_query guardrail error
+
+**Error:** `'dict' object has no attribute 'guardrail_config'`
+
+**Affects:** `db_run_write_query` in some deployments.
+
+**What to do:**
+
+1. Try the call once. If it fails with this specific error, write operations are unavailable in this deployment.
+2. For reads, always use `db_run_read_only_query` (never `db_run_write_query` for SELECT).
+3. Report the issue — it's a server-side bug, not a parameter problem.
+
+---
+
+## knowledgebase_add_source_to_index failure
+
+**Error:** SQL function signature mismatch — the tool passes `r_index_name` (string) but the DB function expects `r_index_id` (UUID).
+
+**What to do:**
+
+1. Do NOT try different parameter formats (string name, UUID, etc.) — the bug is in the tool, not your parameters.
+2. **Workaround:** Use `knowledgebase_trigger_index_creation` with all sources included upfront instead of adding sources incrementally.
+
+---
+
+## Scope parameter errors
+
+**Error:** `Insufficient scope: 'all'. This tool requires 'read' or higher.`
+
+The only valid scope values are: `"read"`, `"write"`, `"admin"`.
+
+- Use `"read"` for all read operations (default choice)
+- Use `"write"` for inserts, updates, creates, memory writes
+- Use `"admin"` only for destructive deletes
+
+**Never use:** `"all"`, `"readwrite"`, `"rw"`, or any other value.
+
+---
+
+## agent_id errors
+
+**Error:** `syntax error at or near "-"` in table creation.
+
+`agent_id` is used in PostgreSQL table names. Hyphens are invalid in unquoted identifiers.
+
+**Rule:** Lowercase letters, digits, underscores only.
+- Good: `"claude_code"`, `"support_bot"`, `"agent_001"`
+- Bad: `"claude-code"`, `"my agent"`, `"agent.one"`
+
+---
+
+## Permission denied on data tables
+
+**Error:** `permission denied for table customer_complaints`
+
+**Why:** The MCP database user may not have read access to all tables, particularly data tables created by the provisioning system within a datapack.
+
+**What to do:**
+
+1. This is a server-side configuration issue — not fixable via MCP tools.
+2. Don't retry. Don't try different query formulations.
+3. Use `db_summarize_database` to see which tables you CAN access.
+4. Report the permission gap to the Meko admin.
+
+---
+
+## Safe-to-retry vs not
+
+| Tool | Safe to retry? | Why |
+|------|---------------|-----|
+| All `read` scope tools | Yes | Reads are idempotent |
+| `memory_add` | Yes (once) | Mem0 has dedup logic |
+| `memory_update` | Yes (once) | Overwrites same ID |
+| `memory_delete_by_id` | Yes | Deleting already-deleted is a no-op |
+| `db_run_write_query` (INSERT) | **No** | May double-insert rows |
+| `db_run_write_query` (CREATE TABLE) | **No** | "Table already exists" error |
+| `knowledgebase_trigger_index_creation` | **No** | Creates duplicate indexes |
+| `conversation_create` | **No** | Creates duplicate conversations |
+| `conversation_add_message` with `seed` | Yes | Seed-based dedup prevents duplicates |
+| `conversation_add_message` without `seed` | **No** | Creates duplicate messages |

package/assets/skills/meko-mcp-tools/references/tools-user-id-conventions.md

@@ -0,0 +1,93 @@
+# user_id Conventions
+
+`user_id` identifies the **human** whose data is being stored or retrieved. It is the user-scoping counterpart to `agent_id`.
+
+> **Note on `agent_id`.** In the current schema `agent_id` is overloaded — it's used for both isolation/namespacing and agent labeling. Discover it via `db_summarize_database` at session start rather than defaulting to the current tool's name. See the main SKILL.md section "Discover the user's `agent_id` namespace" and issue [#10](https://github.com/amiramm/meko-mcp-server/issues/10). The examples below use `claude_code` for illustration; substitute the discovered value at runtime.
+
+## Why user_id matters
+
+Without `user_id`, the server defaults to `{agent_id}_user` — a single undifferentiated bucket. This works for a solo developer in a single session, but breaks the moment:
+
+- A second person uses the same agent
+- An autonomous agent serves multiple end-users
+- You want to retrieve one person's memories without pulling everyone else's
+
+**Always pass `user_id` explicitly.** Relying on the default creates data you can't cleanly separate later.
+
+## The two usage patterns
+
+### Interactive coding agent (e.g., Claude Code)
+
+You are a coding assistant working with one human at a time. You know who they are — use their identity as `user_id`.
+
+```
+memory_add(scope="write", agent_id="claude_code", user_id="alice",
+    text="Prefers concise responses, no emojis.")
+
+memory_search(scope="read", query="response preferences", agent_id="claude_code", user_id="alice")
+
+conversation_create(scope="write", agent_id="claude_code", user_id="alice",
+    title="Debugging auth middleware")
+```
+
+**How to determine user_id:**
+- Use the person's first name, lowercase: `"alice"`, `"bob"`, `"kyle"`
+- If the name is ambiguous within the org, append a qualifier: `"alice_eng"`, `"alice_sales"`
+- Use the same value consistently across all calls in a session — and across sessions
+- If you don't know the user's name yet, ask. Don't fall back to the default.
+
+### Autonomous multi-user agent (e.g., support bot, team assistant)
+
+The agent serves many users. Each user's data must be isolated so memories, conversations, and preferences don't leak across users.
+
+```
+# Serving Alice
+memory_add(scope="write", agent_id="support_bot", user_id="alice_123",
+    text="Alice prefers email communication. Has Pro plan.")
+
+# Serving Bob — completely separate memory space
+memory_add(scope="write", agent_id="support_bot", user_id="bob_456",
+    text="Bob prefers Slack. On Enterprise plan.")
+
+# Searching only returns Alice's memories
+memory_search(scope="read", query="communication preference",
+    agent_id="support_bot", user_id="alice_123")
+```
+
+**How to determine user_id:**
+- Use a stable identifier from your auth/identity system: username, email prefix, or external ID
+- Must be consistent across sessions — the same person must always map to the same `user_id`
+- Keep it human-readable when possible (debugging is easier with `"alice"` than `"usr_8f3a2b"`)
+
+## Scoping behavior
+
+`user_id` filters data at the Mem0/Langfuse layer:
+
+| Call | What it returns |
+|------|----------------|
+| `memory_search(agent_id="bot", user_id="alice")` | Only Alice's memories for this agent |
+| `memory_search(agent_id="bot")` | Memories stored without a `user_id`, or with the default `bot_user` |
+| `memory_get_all(agent_id="bot", user_id="alice")` | All of Alice's memories |
+| `conversation_list(agent_id="bot", user_id="alice")` | Only Alice's conversations |
+
+**Mixing scoped and unscoped calls creates invisible data.** If you store with `user_id="alice"` but search without `user_id`, the search won't find those memories — they live in a different partition. Pick a convention and stick to it.
+
+## Rules summary
+
+1. **Always pass `user_id` explicitly** — never rely on the server default
+2. **Use the human's identity** — first name lowercase, consistent across sessions
+3. **Same `user_id` for store and retrieve** — mismatched scoping creates invisible data
+4. **Ask if you don't know** — it's better to ask the user's name once than to store data you can't find later
+5. **One human = one `user_id`** — don't create separate IDs for the same person across contexts
+
+## Relationship to other parameters
+
+| Parameter | Identifies | Example |
+|-----------|-----------|---------|
+| `agent_id` | The AI agent | `"claude_code"`, `"support_bot"` |
+| `user_id` | The human being served | `"amiram"`, `"alice_123"` |
+| `app_id` | The application/product (optional) | `"second_brain"`, `"helpdesk"` |
+| `run_id` | A specific execution run (optional) | `"run_20260415_001"` |
+| `datapack_id` | The target database/datapack (optional) | `"dp-uuid-123"` |
+
+Together, `agent_id` + `user_id` form the primary namespace for memory and conversation isolation. `app_id` and `run_id` provide optional finer-grained grouping within that namespace.

package/assets/skills/meko-mcp-tools/references/tools-write-guardrails.md

@@ -0,0 +1,30 @@
+# Write Query Guardrails and Blocked Operations
+
+**WRONG:** `"INSERT INTO a (...); INSERT INTO b (...)"` → "Multi-statement queries not allowed." Send one statement per call.
+**WRONG:** `"DROP SCHEMA analytics CASCADE"` → "DROP SCHEMA is not allowed."
+**WRONG:** `"\\d users"` → psql meta-commands not supported. Use `information_schema` queries via `db_run_read_only_query`.
+
+## Blocked Operations
+
+**Database/schema destruction:** `DROP DATABASE`, `DROP SCHEMA`, `ALTER DATABASE`, `CREATE DATABASE`
+**Role/privilege manipulation:** `GRANT`, `REVOKE`, `CREATE/ALTER/DROP ROLE`, `CREATE/ALTER/DROP USER`
+**Filesystem/code execution:** `COPY TO/FROM`, `LOAD`, `DO $$`, `CREATE EXTENSION`
+**Server configuration:** `ALTER SYSTEM`, `RESET ALL`
+**Dangerous functions:** `pg_sleep`, `pg_read_file`, `pg_write_file`, `lo_import`, `lo_export`, `dblink`
+**Structural rules:** One SQL statement per call (multi-statement rejected). No psql `\` commands.
+
+## Configurable Limits
+
+**Bulk INSERT row cap** (default 1000, env: `YB_MCP_MAX_INSERT_ROWS`): Counts parenthesized tuples in VALUES. Does NOT apply to `INSERT ... SELECT`. Split large inserts into batches of 1000 or fewer.
+
+**WHERE clause enforcement** (off by default):
+- `YB_MCP_REQUIRE_WHERE_ON_UPDATE=true` → rejects `UPDATE` without top-level `WHERE`
+- `YB_MCP_REQUIRE_WHERE_ON_DELETE=true` → rejects `DELETE` without top-level `WHERE`
+
+A `WHERE` inside a subquery does NOT satisfy the check.
+
+## What IS Allowed
+
+`INSERT INTO ... VALUES`, `INSERT INTO ... SELECT` (no row limit), `UPDATE ... SET ... WHERE`, `DELETE FROM ... WHERE`, `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE`, `CREATE INDEX`, `TRUNCATE`, `CALL procedure_name(...)`.
+
+SQL comments are stripped before guardrail checks — patterns cannot be hidden in comments.