Tool Filtering

Tool Filtering

AI IDEs like Cursor have tool limits. With 278 tools available, you must use tool filtering to stay within your IDE's limits.

⭐ Code Mode (--tool-filter codemode) is the recommended configuration — it exposes pg_execute_code, a secure, true V8 isolate providing access to all 278 tools' worth of capability with up to 90% token savings. See Presets for alternatives.

---

How It Works

The --tool-filter argument accepts groups or tool names. Mix and match freely.

# Recommended
--tool-filter codemode

# Combine groups
--tool-filter core,jsonb,transactions

# Extend a group with specific tools
--tool-filter core,+pg_stat_statements

# Remove specific tools from a group
--tool-filter core,-pg_drop_table

---

Tool Groups (25 Available)

Important

All tool groups include Code Mode (pg_execute_code) by default. To exclude it, add -codemode to your filter: --tool-filter cron,pgcrypto,-codemode

Group	Tools	Description
codemode	1	Code Mode (sandboxed code execution) 🌟 Recommended
core	21	Read/write queries, tables, indexes, convenience/drop tools
transactions	9	BEGIN, COMMIT, ROLLBACK, savepoints, status
jsonb	21	JSONB manipulation, queries, and pretty-print
text	14	Full-text search, fuzzy matching
performance	25	EXPLAIN, query analysis, optimization, diagnostics, anomaly detection
admin	12	VACUUM, ANALYZE, REINDEX, insights
monitoring	12	Database sizes, connections, status
backup	13	pg_dump, COPY, restore, audit backups
schema	13	Schemas, views, sequences, functions, triggers
introspection	7	Dependency graphs, cascade simulation, schema analysis
migration	7	Schema migration tracking and management
partitioning	7	Native partition management
stats	20	Statistical analysis, window functions, outlier detection
vector	17	pgvector (AI/ML similarity search)
postgis	16	PostGIS (geospatial)
cron	9	pg_cron (job scheduling)
partman	11	pg_partman (auto-partitioning)
kcache	8	pg_stat_kcache (OS-level stats)
citext	7	citext (case-insensitive text)
ltree	9	ltree (hierarchical data)
pgcrypto	10	pgcrypto (encryption, UUIDs)
security	10	Security auditing, SSL, firewall, data masking, privilege analysis
roles	13	Role management, privileges, membership, RLS
docstore	10	JSONB document collections (NoSQL-style CRUD, indexing)

---

Syntax Reference

Prefix	Target	Example	Effect
(none)	Group	core	Whitelist Mode: Enable ONLY this group
(none)	Tool	pg_read_query	Whitelist Mode: Enable ONLY this tool
+	Group	+vector	Add tools from this group to current set
-	Group	-admin	Remove tools in this group from current set
+	Tool	+pg_explain	Add one specific tool
-	Tool	-pg_drop_table	Remove one specific tool

Custom Tool Selection

You can list individual tool names (without + prefix) to create a fully custom whitelist — only the tools you specify will be enabled:

# Enable exactly 3 tools (whitelist mode)
--tool-filter "pg_read_query,pg_write_query,pg_list_tables"

# Mix tools from different groups
--tool-filter "pg_read_query,pg_explain,pg_vector_search"

# Combine a group with specific tools
--tool-filter "core,+pg_vector_search,+pg_fuzzy_match"

This is useful for scripted or automated clients that need a minimal, precise set of capabilities.

---

Common Configurations

Recommended (1 tool)

Code Mode connects securely to a sandbox and lets the AI use all 278 API boundaries context-free:

{
  "args": ["--tool-filter", "codemode"]
}

Granular AI Data Analysis (37 tools)

Use JSONB and text groups exclusively along with Code Mode.

{
  "args": ["--tool-filter", "jsonb,text"]
}

Non-Admin Users (No Code Mode)

If you don't have admin access or prefer individual tool calls (Code Mode requires admin scope):

{
  "args": ["--tool-filter", "core,jsonb,transactions,-codemode"]
}

---

Architecture Note

If you start with a negative filter (e.g., -base,-extensions), the system assumes you want all tools enabled first, then subtracts. This is permitted but computationally heavier than whitelisting, and generally not recommended for LLMs.

---

Related

• Code-Mode - Full Code Mode documentation
• Quick-Start - Installation and first steps