search_objects

The search_objects tool provides a unified interface for searching and listing database objects (schemas, tables, columns, procedures, functions, indexes) with progressive disclosure to optimize token usage.

Progressive Disclosure Design

The tool uses a detail_level parameter to control how much information is returned:

names - Returns only object names (minimal tokens) - ideal for initial discovery
summary - Includes names plus metadata (row counts, column counts, etc.)
full - Returns complete structure details including columns, indexes, parameters, etc.

This design minimizes token usage by allowing you to request only the information you need.

Parameters

object_type

enum

required

Type of database object to search for.Options:

schema - Database schemas/namespaces
table - Tables and views
column - Table columns
procedure - Stored procedures
function - User-defined functions
index - Table indexes

pattern

string

default:"%"

SQL LIKE pattern for matching object names. Uses standard SQL wildcards:

% - Matches any sequence of characters
_ - Matches exactly one character

Examples:

"%user%" - Contains “user” anywhere
"user_%" - Starts with “user_”
"%_id" - Ends with “_id”
"%" - Matches everything (default, for listing all objects)

schema

string

Filter results to a specific schema. Required when using table parameter.Example: "public" or "dbo"

table

string

Filter results to a specific table. Only valid for object_type="column" or object_type="index". Requires schema parameter.Example: "users"

detail_level

enum

default:"names"

Controls the amount of detail returned.Options:

names - Minimal: just object names (most token-efficient)
summary - Metadata: names + row counts, column counts, etc.
full - Complete: full structure including columns, indexes, parameters

limit

number

default:"100"

Maximum number of results to return. Range: 1-1000.

source_id

string

Optional database identifier for multi-database configurations.

Response Format

object_type

string

The type of objects returned (echoes the request parameter).

pattern

string

The pattern used for matching (echoes the request parameter).

schema

string

The schema filter applied (if any).

table

string

The table filter applied (if any).

detail_level

string

The detail level returned (echoes the request parameter).

count

number

Number of results returned.

results

array

Array of matching objects. Structure varies by object_type and detail_level.

truncated

boolean

True if results were limited by the limit parameter (more results exist).

Examples by Object Type

List All Schemas

Request:

{
  "object_type": "schema",
  "detail_level": "summary"
}

Response:

{
  "object_type": "schema",
  "pattern": "%",
  "detail_level": "summary",
  "count": 3,
  "results": [
    { "name": "public", "table_count": 45 },
    { "name": "analytics", "table_count": 12 },
    { "name": "staging", "table_count": 8 }
  ],
  "truncated": false
}

Search for Tables Containing “user”

Request:

{
  "object_type": "table",
  "pattern": "%user%",
  "detail_level": "summary"
}

Response:

{
  "object_type": "table",
  "pattern": "%user%",
  "detail_level": "summary",
  "count": 3,
  "results": [
    {
      "name": "users",
      "schema": "public",
      "column_count": 8,
      "row_count": 15234,
      "comment": "User accounts and profiles"
    },
    {
      "name": "user_sessions",
      "schema": "public",
      "column_count": 5,
      "row_count": 89123
    },
    {
      "name": "user_preferences",
      "schema": "public",
      "column_count": 12,
      "row_count": 14890
    }
  ],
  "truncated": false
}

Get Full Schema for a Specific Table

Request:

{
  "object_type": "table",
  "pattern": "users",
  "schema": "public",
  "detail_level": "full"
}

Response:

{
  "object_type": "table",
  "pattern": "users",
  "schema": "public",
  "detail_level": "full",
  "count": 1,
  "results": [
    {
      "name": "users",
      "schema": "public",
      "column_count": 8,
      "row_count": 15234,
      "comment": "User accounts and profiles",
      "columns": [
        {
          "name": "id",
          "type": "integer",
          "nullable": false,
          "default": "nextval('users_id_seq'::regclass)"
        },
        {
          "name": "email",
          "type": "character varying(255)",
          "nullable": false,
          "default": null
        },
        {
          "name": "name",
          "type": "character varying(100)",
          "nullable": false,
          "default": null
        },
        {
          "name": "created_at",
          "type": "timestamp with time zone",
          "nullable": false,
          "default": "now()"
        }
      ],
      "indexes": [
        {
          "name": "users_pkey",
          "columns": ["id"],
          "unique": true,
          "primary": true
        },
        {
          "name": "users_email_key",
          "columns": ["email"],
          "unique": true,
          "primary": false
        }
      ]
    }
  ],
  "truncated": false
}

Search for Columns Named “email”

Request:

{
  "object_type": "column",
  "pattern": "email",
  "detail_level": "summary"
}

Response:

{
  "object_type": "column",
  "pattern": "email",
  "detail_level": "summary",
  "count": 3,
  "results": [
    {
      "name": "email",
      "table": "users",
      "schema": "public",
      "type": "character varying(255)",
      "nullable": false,
      "default": null
    },
    {
      "name": "email",
      "table": "subscribers",
      "schema": "public",
      "type": "character varying(255)",
      "nullable": false,
      "default": null
    },
    {
      "name": "email",
      "table": "contact_requests",
      "schema": "public",
      "type": "text",
      "nullable": true,
      "default": null
    }
  ],
  "truncated": false
}

List All Columns in a Specific Table

Request:

{
  "object_type": "column",
  "schema": "public",
  "table": "users",
  "detail_level": "summary"
}

Response:

{
  "object_type": "column",
  "pattern": "%",
  "schema": "public",
  "table": "users",
  "detail_level": "summary",
  "count": 8,
  "results": [
    {
      "name": "id",
      "table": "users",
      "schema": "public",
      "type": "integer",
      "nullable": false,
      "default": "nextval('users_id_seq'::regclass)"
    },
    {
      "name": "email",
      "table": "users",
      "schema": "public",
      "type": "character varying(255)",
      "nullable": false,
      "default": null
    }
  ],
  "truncated": false
}

Find Stored Procedures Starting with “get_”

Request:

{
  "object_type": "procedure",
  "pattern": "get_%",
  "detail_level": "full"
}

Response:

{
  "object_type": "procedure",
  "pattern": "get_%",
  "detail_level": "full",
  "count": 2,
  "results": [
    {
      "name": "get_user_by_email",
      "schema": "public",
      "type": "FUNCTION",
      "language": "plpgsql",
      "parameters": "email_param character varying",
      "return_type": "users",
      "definition": "BEGIN\n  RETURN QUERY SELECT * FROM users WHERE email = email_param;\nEND;"
    },
    {
      "name": "get_active_users",
      "schema": "public",
      "type": "FUNCTION",
      "language": "sql",
      "parameters": "",
      "return_type": "SETOF users",
      "definition": "SELECT * FROM users WHERE active = true;"
    }
  ],
  "truncated": false
}

List All Indexes for a Table

Request:

{
  "object_type": "index",
  "schema": "public",
  "table": "users",
  "detail_level": "summary"
}

Response:

{
  "object_type": "index",
  "pattern": "%",
  "schema": "public",
  "table": "users",
  "detail_level": "summary",
  "count": 3,
  "results": [
    {
      "name": "users_pkey",
      "table": "users",
      "schema": "public",
      "columns": ["id"],
      "unique": true,
      "primary": true
    },
    {
      "name": "users_email_key",
      "table": "users",
      "schema": "public",
      "columns": ["email"],
      "unique": true,
      "primary": false
    },
    {
      "name": "idx_users_created_at",
      "table": "users",
      "schema": "public",
      "columns": ["created_at"],
      "unique": false,
      "primary": false
    }
  ],
  "truncated": false
}

Error Handling

SCHEMA_REQUIRED

Occurs when table parameter is provided without schema:

{
  "error": "The 'table' parameter requires 'schema' to be specified",
  "code": "SCHEMA_REQUIRED"
}

INVALID_TABLE_FILTER

Occurs when table parameter is used with incompatible object_type:

{
  "error": "The 'table' parameter only applies to object_type 'column' or 'index', not 'procedure'",
  "code": "INVALID_TABLE_FILTER"
}

SCHEMA_NOT_FOUND

Occurs when specified schema doesn’t exist:

{
  "error": "Schema 'nonexistent' does not exist. Available schemas: public, analytics, staging",
  "code": "SCHEMA_NOT_FOUND"
}

SEARCH_ERROR

Occurs when the search operation fails:

{
  "error": "Error searching database objects: connection timeout",
  "code": "SEARCH_ERROR"
}

Token Efficiency Strategy

The tool is designed to minimize token usage through progressive disclosure:

Start with names - Get a quick overview with minimal tokens
Refine with summary - Add metadata when you need context
Drill down with full - Get complete details only when necessary

Example Workflow

// Step 1: Discover what tables exist (minimal tokens)
{ "object_type": "table", "detail_level": "names" }
// Returns: ["users", "orders", "products", ...]

// Step 2: Get metadata for tables of interest (moderate tokens)
{ "object_type": "table", "pattern": "user%", "detail_level": "summary" }
// Returns: column counts, row counts, comments

// Step 3: Get full schema only when needed (high tokens)
{ "object_type": "table", "pattern": "users", "detail_level": "full" }
// Returns: complete column definitions, indexes, constraints

Implementation Details

Source: src/tools/search-objects.ts
Pattern matching: Converts SQL LIKE patterns to JavaScript regex
Row counts: Uses database statistics (e.g., pg_class.reltuples) when available
Performance: Skips inaccessible schemas/tables gracefully
Database support: PostgreSQL, MySQL, MariaDB, SQL Server, SQLite

Best Practices

Use names detail level for initial discovery to minimize tokens
Specify schema filters when possible to reduce search scope
Use specific patterns instead of % to limit results
Set appropriate limits based on expected result sizes
Progress from names → summary → full as you narrow your focus
Use table filters for column/index searches to improve performance

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

search_objects

Progressive Disclosure Design

Parameters

Response Format

Examples by Object Type

List All Schemas

Search for Tables Containing “user”

Get Full Schema for a Specific Table

Search for Columns Named “email”

List All Columns in a Specific Table

Find Stored Procedures Starting with “get_”

List All Indexes for a Table

Error Handling

SCHEMA_REQUIRED

INVALID_TABLE_FILTER

SCHEMA_NOT_FOUND

SEARCH_ERROR

Token Efficiency Strategy

Example Workflow

Implementation Details

Best Practices

Build docs developers (and LLMs) love

Get Started

Configuration

Database Connectors

MCP Tools

Workbench

Guides

​Progressive Disclosure Design

​Parameters

​Response Format

​Examples by Object Type

​List All Schemas

​Search for Tables Containing “user”

​Get Full Schema for a Specific Table

​Search for Columns Named “email”

​List All Columns in a Specific Table

​Find Stored Procedures Starting with “get_”

​List All Indexes for a Table

​Error Handling

​SCHEMA_REQUIRED

​INVALID_TABLE_FILTER

​SCHEMA_NOT_FOUND

​SEARCH_ERROR

​Token Efficiency Strategy

​Example Workflow

​Implementation Details

​Best Practices

Build docs developers (and LLMs) love

Progressive Disclosure Design

Parameters

Response Format

Examples by Object Type

List All Schemas

Search for Tables Containing “user”

Get Full Schema for a Specific Table

Search for Columns Named “email”

List All Columns in a Specific Table

Find Stored Procedures Starting with “get_”

List All Indexes for a Table

Error Handling

SCHEMA_REQUIRED

INVALID_TABLE_FILTER

SCHEMA_NOT_FOUND

SEARCH_ERROR

Token Efficiency Strategy

Example Workflow

Implementation Details

Best Practices