Tools Overview - Isthmus

Isthmus exposes three MCP tools that AI models call to explore and query your PostgreSQL database. You don’t call these tools directly — your AI client (Claude, Cursor, etc.) invokes them automatically based on your questions.

Recommended discovery workflow

When an AI model connects to your database for the first time, the most effective sequence is:

discover          → What schemas and tables exist? (sizes, row counts, columns)
describe_table    → Full table analysis: columns, types, keys, stats, sample rows, index usage
query             → Execute a read-only SQL query (with optional EXPLAIN plan)

Most AI models follow this pattern naturally — they start broad with discover, narrow down to specific tables with describe_table, then write and execute SQL with query.

Tool summary

Tool	Purpose	Parameters
`discover`	Full database landscape: schemas with nested tables	(none)
`describe_table`	Complete table analysis: columns, statistics, sample rows, index usage	`table_name` (required), `schema`
`query`	Execute read-only SQL with optional EXPLAIN plans	`sql` (required), `explain`, `analyze`

Safety guardrails

All tools operate within Isthmus’s safety model:

Read-only transactions — queries cannot modify data
SQL validation — only SELECT and EXPLAIN statements are allowed (enforced via PostgreSQL AST parsing)
Row limits — configurable max rows per query (default: 100)
Query timeout — configurable timeout (default: 10s)
Schema filtering — only expose the schemas you choose

See Security for the full safety model.