Add comprehensive tool API documentation

[sgaunet]

Problem

The MCP tools lack detailed API documentation for their exact output formats, error messages, and behavior. While CLAUDE.md mentions tools, detailed specifications are missing.

Missing Documentation

Users need clear documentation for:

1. execute_query

• Exact output format structure
• How different PostgreSQL types are mapped to JSON
• Maximum result set size limits
• Error codes and messages
• Example requests and responses

2. explain_query

• Output format interpretation
• How to read execution plans
• What metrics are important
• Example explain output

3. list_indexes

• Column ordering in results
• What index types are supported
• How composite indexes are represented
• Example output structure

4. get_table_stats

• What statistics are included
• How estimates vs actual counts work
• Size calculation methodology
• Example output with descriptions

5. All tools

• Parameter validation rules
• Error message catalog
• Authentication/authorization requirements
• Rate limits (if any)

Proposed Solution

Create comprehensive tool documentation:

Structure

docs/
├── tools/
│   ├── README.md                    # Overview of all tools
│   ├── connect_database.md          # Connection tool
│   ├── list_databases.md            # Database listing
│   ├── list_schemas.md              # Schema listing
│   ├── list_tables.md               # Table listing
│   ├── describe_table.md            # Table structure
│   ├── execute_query.md             # Query execution
│   ├── list_indexes.md              # Index information
│   ├── explain_query.md             # Query plans
│   └── get_table_stats.md           # Statistics
├── examples/
│   ├── basic_queries.md             # Common usage patterns
│   ├── performance_analysis.md      # Using explain and stats
│   └── error_handling.md            # Handling errors
└── api_reference.md                 # Complete API reference

Documentation Template

For each tool:

# Tool: execute_query

## Description
Executes a read-only SQL query against the connected database.

## Parameters

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| query     | string | Yes      | SQL SELECT or WITH query |

## Response Format

```json
{
  "content": [
    {
      "type": "text",
      "text": "[{\"column1\": \"value1\", \"column2\": 123}, ...]"
    }
  ]
}

Type Mapping

PostgreSQL Type	JSON Type	Notes
INTEGER	number	Direct mapping
TEXT	string	Direct mapping
TIMESTAMP	string	ISO 8601 format
BOOLEAN	boolean	true/false
JSONB	object	Parsed as JSON
ARRAY	array	PostgreSQL arrays

Error Codes

Error	Description	Resolution
invalid_query	Query is not SELECT/WITH	Use read-only query
execution_failed	Database error	Check query syntax
not_connected	No database connection	Connect first

Examples

Basic Query

Request:

{
  "tool": "execute_query",
  "arguments": {
    "query": "SELECT id, name FROM users LIMIT 5"
  }
}

Response:

[
  {"id": 1, "name": "Alice"},
  {"id": 2, "name": "Bob"}
]

Error Example

Request:

{
  "query": "DROP TABLE users"
}

Response:

{
  "error": "invalid_query: Only SELECT and WITH queries are allowed"
}

Limitations

• Maximum result set: 10,000 rows (configurable)
• Maximum query length: 1MB
• Read-only operations only
• No transaction support

See Also

• explain_query - Analyze query performance
• Error Handling Guide

## Impact

- **Severity**: LOW
- **Type**: Documentation
- **Benefits**: Better user experience, reduced support questions

## Checklist

- [ ] Create docs/tools/ directory structure
- [ ] Document all 9 MCP tools with detailed specifications
- [ ] Add example requests and responses for each tool
- [ ] Document type mappings and error codes
- [ ] Create usage examples and common patterns
- [ ] Add API reference with all parameters and outputs
- [ ] Link documentation from main README
- [ ] Add troubleshooting guide