The PostgreSQL MCP server defines 3 tools with clear read-only semantics and basic input validation. Tool names follow verb-noun convention (postgres_query, list_tables, describe_table), which is good. However, there are significant gaps: parameter descriptions are minimal, output schemas are undocumented in the tool definitions, and error handling lacks recovery guidance. The descriptions are adequate (50-80 chars) but do not explain when/why to use each tool or what the LLM can expect in responses. The `postgres_query` tool has a query parameter with a basic description, but there is no documentation of the output structure (columns, rows, count fields). The `list_tables` and `describe_table` tools have no input parameters documented beyond what's visible in the parameter schema. Error messages returned are somewhat helpful (e.g., including schema info on column/table errors), but lack explicit guidance on retry strategies or next steps for the agent.

• Document the output schema for postgres_query: 'Returns a JSON object with {columns: [string], rows: [{key: value, ...}], count: number}. Each row is a map from column name to the value in that row.'
• Document the output schema for list_tables: 'Returns a JSON array of table names as strings, e.g., ["users", "orders"]. Tables are from the public schema only.'
• Document the output schema for describe_table: 'Returns a JSON array of objects, each with {column: string, type: string}, representing the columns of the specified table in ordinal order.'
• Add constraints to the query parameter: 'Must be a SELECT or WITH (CTE) query. No INSERT, UPDATE, DELETE, DROP, ALTER, GRANT, or REVOKE statements. Maximum 10000 characters. Execution will timeout after 30 seconds.'
• Enhance error handling to include recovery hints: e.g., 'Query failed: column "user_id" does not exist. Available columns in table "users": id, name, email. Try correcting the column name and retry.'
• Add a dependency hint to list_tables description: 'Call this tool first if you do not know the names of available tables.'
• Add a usage pattern hint to describe_table: 'Call this tool after list_tables to understand the structure of a specific table before writing a query with postgres_query.'
• Consider adding an optional parameter to list_tables to filter by pattern (e.g., 'table_pattern': 'user%') to reduce the response size for large schemas.
• Document the query parameter format more explicitly: 'The query is a PostgreSQL SELECT or CTE statement. Table and column names are case-sensitive unless quoted.'

Inferred effective spec: <=2025-11-25.

• Relies on Logging (deprecated) - log to stderr or use OpenTelemetry