diff --git a/claudedocs/API_REFERENCE.md b/claudedocs/API_REFERENCE.md
new file mode 100644
index 0000000..255c6e4
--- /dev/null
+++ b/claudedocs/API_REFERENCE.md
@@ -0,0 +1,544 @@
+# incident.io API Client Reference
+
+Comprehensive documentation for the incident.io V2 API Go client library.
+
+## Table of Contents
+
+- [Client Initialization](#client-initialization)
+- [Incidents API](#incidents-api)
+- [Alerts API](#alerts-api)
+- [Alert Routes API](#alert-routes-api)
+- [Alert Sources & Events API](#alert-sources--events-api)
+- [Workflows API](#workflows-api)
+- [Actions API](#actions-api)
+- [Roles & Users API](#roles--users-api)
+- [Severities API](#severities-api)
+- [Incident Types API](#incident-types-api)
+- [Incident Updates API](#incident-updates-api)
+- [Catalog API](#catalog-api)
+- [Error Handling](#error-handling)
+
+---
+
+## Client Initialization
+
+### Creating a Client
+
+Location: `internal/incidentio/client.go:26-49`
+
+```go
+client, err := incidentio.NewClient()
+```
+
+**Environment Variables:**
+- `INCIDENT_IO_API_KEY` (required) - Your incident.io API key
+- `INCIDENT_IO_BASE_URL` (optional) - Custom API base URL (defaults to `https://api.incident.io/v2`)
+
+**Returns:**
+- `*Client` - Configured HTTP client with authentication
+- `error` - Error if API key is missing
+
+**Configuration:**
+- Timeout: 30 seconds
+- TLS: Minimum TLS 1.2
+- User-Agent: `incidentio-mcp-server/0.1.0`
+
+---
+
+## Incidents API
+
+Location: `internal/incidentio/incidents.go`
+
+### List Incidents
+
+```go
+func (c *Client) ListIncidents(opts *ListIncidentsOptions) (*ListIncidentsResponse, error)
+```
+
+**Options:**
+```go
+type ListIncidentsOptions struct {
+    PageSize int      // Max 250, default 25
+    Status   []string // Filter by status: triage, active, resolved, closed
+    Severity []string // Filter by severity IDs
+}
+```
+
+**Response:**
+```go
+type ListIncidentsResponse struct {
+    Incidents []Incident `json:"incidents"`
+}
+```
+
+**Example:**
+```go
+resp, err := client.ListIncidents(&incidentio.ListIncidentsOptions{
+    PageSize: 50,
+    Status:   []string{"active", "triage"},
+})
+```
+
+### Get Incident
+
+```go
+func (c *Client) GetIncident(id string) (*Incident, error)
+```
+
+**Parameters:**
+- `id` - Incident ID (e.g., "INC-123")
+
+**Returns:**
+- `*Incident` - Full incident details
+- `error` - HTTP 404 if incident not found
+
+### Create Incident
+
+```go
+func (c *Client) CreateIncident(req *CreateIncidentRequest) (*Incident, error)
+```
+
+**Request:**
+```go
+type CreateIncidentRequest struct {
+    IdempotencyKey           string `json:"idempotency_key"`
+    Name                     string `json:"name"`
+    Summary                  string `json:"summary,omitempty"`
+    IncidentStatusID         string `json:"incident_status_id,omitempty"`
+    SeverityID               string `json:"severity_id,omitempty"`
+    IncidentTypeID           string `json:"incident_type_id,omitempty"`
+    Mode                     string `json:"mode"` // standard, retrospective, tutorial
+    Visibility               string `json:"visibility"` // public, private
+    SlackChannelNameOverride string `json:"slack_channel_name_override,omitempty"`
+}
+```
+
+**Required Fields:**
+- `IdempotencyKey` - Unique key to prevent duplicate creation
+- `Name` - Incident title
+
+**Example:**
+```go
+incident, err := client.CreateIncident(&incidentio.CreateIncidentRequest{
+    IdempotencyKey: "mcp-1234567890-incident-name",
+    Name:           "Database performance degradation",
+    Summary:        "Users experiencing slow query responses",
+    SeverityID:     "severity-01HXYZ...",
+    IncidentTypeID: "type-01HXYZ...",
+    Mode:           "standard",
+    Visibility:     "public",
+})
+```
+
+### Update Incident
+
+```go
+func (c *Client) UpdateIncident(id string, req *UpdateIncidentRequest) (*Incident, error)
+```
+
+**Request:**
+```go
+type UpdateIncidentRequest struct {
+    Name             string `json:"name,omitempty"`
+    Summary          string `json:"summary,omitempty"`
+    IncidentStatusID string `json:"incident_status_id,omitempty"`
+    SeverityID       string `json:"severity_id,omitempty"`
+}
+```
+
+**Example:**
+```go
+updated, err := client.UpdateIncident("INC-123", &incidentio.UpdateIncidentRequest{
+    Summary:    "Issue resolved after restarting database",
+    SeverityID: "severity-low",
+})
+```
+
+### Incident Type
+
+```go
+type Incident struct {
+    ID             string          `json:"id"`
+    Name           string          `json:"name"`
+    Summary        string          `json:"summary"`
+    Status         IncidentStatus  `json:"incident_status"`
+    Severity       Severity        `json:"severity"`
+    IncidentType   IncidentType    `json:"incident_type"`
+    Mode           string          `json:"mode"`
+    Visibility     string          `json:"visibility"`
+    CreatedAt      time.Time       `json:"created_at"`
+    UpdatedAt      time.Time       `json:"updated_at"`
+    SlackChannelID string          `json:"slack_channel_id"`
+    Permalink      string          `json:"permalink"`
+}
+```
+
+---
+
+## Alerts API
+
+Location: `internal/incidentio/alerts.go`
+
+### List Alerts
+
+```go
+func (c *Client) ListAlerts(opts *ListAlertsOptions) (*ListAlertsResponse, error)
+```
+
+**Options:**
+```go
+type ListAlertsOptions struct {
+    PageSize int      // Max 250
+    Status   []string // Filter by status
+}
+```
+
+### Get Alert
+
+```go
+func (c *Client) GetAlert(id string) (*Alert, error)
+```
+
+### List Alerts for Incident
+
+```go
+func (c *Client) ListAlertsForIncident(incidentID string) (*ListAlertsResponse, error)
+```
+
+**Example:**
+```go
+alerts, err := client.ListAlertsForIncident("INC-123")
+```
+
+---
+
+## Alert Routes API
+
+Location: `internal/incidentio/alert_routes.go`
+
+### List Alert Routes
+
+```go
+func (c *Client) ListAlertRoutes(opts *ListAlertRoutesOptions) (*ListAlertRoutesResponse, error)
+```
+
+### Get Alert Route
+
+```go
+func (c *Client) GetAlertRoute(id string) (*AlertRoute, error)
+```
+
+### Create Alert Route
+
+```go
+func (c *Client) CreateAlertRoute(req *CreateAlertRouteRequest) (*AlertRoute, error)
+```
+
+### Update Alert Route
+
+```go
+func (c *Client) UpdateAlertRoute(id string, req *UpdateAlertRouteRequest) (*AlertRoute, error)
+```
+
+---
+
+## Alert Sources & Events API
+
+Location: `internal/incidentio/alert_sources.go`, `internal/incidentio/alert_events.go`
+
+### List Alert Sources
+
+```go
+func (c *Client) ListAlertSources(opts *ListAlertSourcesOptions) (*ListAlertSourcesResponse, error)
+```
+
+### Create Alert Event
+
+```go
+func (c *Client) CreateAlertEvent(req *CreateAlertEventRequest) (*CreateAlertEventResponse, error)
+```
+
+**Request:**
+```go
+type CreateAlertEventRequest struct {
+    AlertSourceID string                 `json:"alert_source_id"`
+    Payload       map[string]interface{} `json:"payload"`
+}
+```
+
+---
+
+## Workflows API
+
+Location: `internal/incidentio/workflows.go`
+
+### List Workflows
+
+```go
+func (c *Client) ListWorkflows(opts *ListWorkflowsOptions) (*ListWorkflowsResponse, error)
+```
+
+### Get Workflow
+
+```go
+func (c *Client) GetWorkflow(id string) (*Workflow, error)
+```
+
+### Update Workflow
+
+```go
+func (c *Client) UpdateWorkflow(id string, req *UpdateWorkflowRequest) (*Workflow, error)
+```
+
+---
+
+## Actions API
+
+Location: `internal/incidentio/actions.go`
+
+### List Actions
+
+```go
+func (c *Client) ListActions(opts *ListActionsOptions) (*ListActionsResponse, error)
+```
+
+### Get Action
+
+```go
+func (c *Client) GetAction(id string) (*Action, error)
+```
+
+---
+
+## Roles & Users API
+
+Location: `internal/incidentio/roles.go`
+
+### List Incident Roles
+
+```go
+func (c *Client) ListIncidentRoles(opts *ListIncidentRolesOptions) (*ListIncidentRolesResponse, error)
+```
+
+### List Users
+
+```go
+func (c *Client) ListUsers(opts *ListUsersOptions) (*ListUsersResponse, error)
+```
+
+**Options:**
+```go
+type ListUsersOptions struct {
+    PageSize int
+    Email    string // Filter by email
+}
+```
+
+### Assign Incident Role
+
+```go
+func (c *Client) AssignIncidentRole(incidentID string, req *AssignIncidentRoleRequest) (*AssignIncidentRoleResponse, error)
+```
+
+**Request:**
+```go
+type AssignIncidentRoleRequest struct {
+    RoleID   string `json:"role_id"`
+    Assignee struct {
+        ID string `json:"id"`
+    } `json:"assignee"`
+}
+```
+
+---
+
+## Severities API
+
+Location: `internal/incidentio/severities.go`
+
+### List Severities
+
+```go
+func (c *Client) ListSeverities(opts *ListSeveritiesOptions) (*ListSeveritiesResponse, error)
+```
+
+### Get Severity
+
+```go
+func (c *Client) GetSeverity(id string) (*Severity, error)
+```
+
+**Severity Type:**
+```go
+type Severity struct {
+    ID          string `json:"id"`
+    Name        string `json:"name"`
+    Description string `json:"description"`
+    Rank        int    `json:"rank"` // Lower rank = higher severity
+}
+```
+
+---
+
+## Incident Types API
+
+Location: `internal/incidentio/incident_types.go`
+
+### List Incident Types
+
+```go
+func (c *Client) ListIncidentTypes(opts *ListIncidentTypesOptions) (*ListIncidentTypesResponse, error)
+```
+
+**Response:**
+```go
+type IncidentType struct {
+    ID          string `json:"id"`
+    Name        string `json:"name"`
+    Description string `json:"description"`
+}
+```
+
+---
+
+## Incident Updates API
+
+Location: `internal/incidentio/incident_updates.go`
+
+### List Incident Updates
+
+```go
+func (c *Client) ListIncidentUpdates(incidentID string, opts *ListIncidentUpdatesOptions) (*ListIncidentUpdatesResponse, error)
+```
+
+### Get Incident Update
+
+```go
+func (c *Client) GetIncidentUpdate(incidentID, updateID string) (*IncidentUpdate, error)
+```
+
+### Create Incident Update
+
+```go
+func (c *Client) CreateIncidentUpdate(incidentID string, req *CreateIncidentUpdateRequest) (*IncidentUpdate, error)
+```
+
+**Request:**
+```go
+type CreateIncidentUpdateRequest struct {
+    Message string `json:"message"`
+}
+```
+
+### Delete Incident Update
+
+```go
+func (c *Client) DeleteIncidentUpdate(incidentID, updateID string) error
+```
+
+---
+
+## Catalog API
+
+Location: `internal/incidentio/catalog.go`
+
+### List Catalog Types
+
+```go
+func (c *Client) ListCatalogTypes(opts *ListCatalogTypesOptions) (*ListCatalogTypesResponse, error)
+```
+
+### List Catalog Entries
+
+```go
+func (c *Client) ListCatalogEntries(catalogTypeID string, opts *ListCatalogEntriesOptions) (*ListCatalogEntriesResponse, error)
+```
+
+### Update Catalog Entry
+
+```go
+func (c *Client) UpdateCatalogEntry(catalogTypeID, entryID string, req *UpdateCatalogEntryRequest) (*CatalogEntry, error)
+```
+
+---
+
+## Error Handling
+
+Location: `internal/incidentio/client.go:117-122`
+
+All API methods return errors with the following format:
+
+```go
+type ErrorResponse struct {
+    Error struct {
+        Message string `json:"message"`
+        Code    string `json:"code"`
+    } `json:"error"`
+}
+```
+
+**Common Error Patterns:**
+
+```go
+// API errors (HTTP 4xx/5xx)
+if err != nil {
+    // Format: "API error: <message> (HTTP <status>)"
+    return err
+}
+
+// 404 Not Found
+incident, err := client.GetIncident("invalid-id")
+// Returns: "API error: Incident not found (HTTP 404)"
+
+// Authentication errors
+// Returns: "API error: Unauthorized (HTTP 401)"
+
+// Validation errors
+// Returns: "API error: severity_id is required (HTTP 422)"
+```
+
+**Best Practices:**
+
+1. Always check for nil errors after API calls
+2. Use specific error messages to guide users
+3. HTTP 404 errors indicate resource not found
+4. HTTP 422 errors indicate validation failures
+5. HTTP 401/403 errors indicate authentication/authorization issues
+
+**Example Error Handling:**
+
+```go
+incident, err := client.GetIncident(id)
+if err != nil {
+    if strings.Contains(err.Error(), "404") {
+        return fmt.Errorf("incident %s not found", id)
+    }
+    return fmt.Errorf("failed to get incident: %w", err)
+}
+```
+
+---
+
+## HTTP Client Configuration
+
+The client uses a custom HTTP transport with:
+
+- **Timeout**: 30 seconds per request
+- **TLS**: Minimum version TLS 1.2
+- **Headers**:
+  - `Authorization: Bearer <api_key>`
+  - `Content-Type: application/json`
+  - `User-Agent: incidentio-mcp-server/0.1.0`
+
+**Extending the Client:**
+
+```go
+// Access base URL
+baseURL := client.BaseURL()
+
+// Change base URL (for testing)
+client.SetBaseURL("https://test.incident.io/v2")
+
+// Make custom requests
+resp, err := client.DoRequest("GET", "/custom/endpoint", nil, nil)
+```
diff --git a/claudedocs/ARCHITECTURE.md b/claudedocs/ARCHITECTURE.md
new file mode 100644
index 0000000..0451ad7
--- /dev/null
+++ b/claudedocs/ARCHITECTURE.md
@@ -0,0 +1,664 @@
+# Architecture Documentation
+
+Comprehensive architectural documentation for the incident.io MCP server.
+
+## Table of Contents
+
+- [System Overview](#system-overview)
+- [Architecture Layers](#architecture-layers)
+- [Component Design](#component-design)
+- [Data Flow](#data-flow)
+- [MCP Protocol Implementation](#mcp-protocol-implementation)
+- [Design Patterns](#design-patterns)
+- [Testing Strategy](#testing-strategy)
+- [Deployment Architecture](#deployment-architecture)
+
+---
+
+## System Overview
+
+The incident.io MCP server is a Go-based implementation of the Model Context Protocol (MCP) that provides tools for interacting with the incident.io V2 API.
+
+### Key Characteristics
+
+- **Protocol**: MCP (Model Context Protocol) via JSON-RPC 2.0
+- **Language**: Go 1.21+
+- **Architecture Style**: Layered, modular design
+- **Communication**: stdin/stdout streaming
+- **API Integration**: RESTful HTTP client for incident.io V2
+
+### System Context
+
+```
+┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐
+│   MCP Client    │◄───────►│   MCP Server     │◄───────►│  incident.io    │
+│  (e.g., Claude) │  stdio  │  (This project)  │  HTTPS  │     API V2      │
+└─────────────────┘         └──────────────────┘         └─────────────────┘
+```
+
+---
+
+## Architecture Layers
+
+### Layer 1: Entry Point Layer
+
+**Location**: `cmd/mcp-server/main.go`
+
+**Responsibilities:**
+- Process lifecycle management
+- Signal handling (SIGINT, SIGTERM)
+- Server initialization and startup
+- Tool registration coordination
+
+**Key Components:**
+```go
+type MCPServer struct {
+    tools map[string]tools.Tool
+}
+```
+
+**Design Decisions:**
+- Single binary entry point for simplicity
+- Graceful shutdown support
+- Logging to stderr (stdout reserved for MCP protocol)
+
+---
+
+### Layer 2: Server Layer
+
+**Location**: `internal/server/server.go`
+
+**Responsibilities:**
+- MCP protocol message handling
+- JSON-RPC 2.0 compliance
+- Message routing and dispatch
+- Tool registry management
+
+**Message Flow:**
+```
+stdin → Decoder → Message Handler → Tool Executor → Encoder → stdout
+```
+
+**Supported Methods:**
+- `initialize` - Protocol handshake
+- `initialized` - Notification (no response)
+- `tools/list` - Enumerate available tools
+- `tools/call` - Execute specific tool
+
+**Error Handling:**
+- JSON-RPC 2.0 error codes (-32700, -32600, -32601, -32602, -32603)
+- Graceful degradation for malformed messages
+- Proper error responses with request IDs
+
+---
+
+### Layer 3: Tools Layer
+
+**Location**: `internal/tools/`
+
+**Responsibilities:**
+- Tool interface implementation
+- Input validation and schema definition
+- Business logic orchestration
+- Response formatting
+
+**Tool Structure:**
+```go
+type Tool interface {
+    Name() string
+    Description() string
+    InputSchema() map[string]interface{}
+    Execute(args map[string]interface{}) (string, error)
+}
+```
+
+**Tool Categories:**
+1. **Incident Management** - CRUD operations on incidents
+2. **Alert Management** - Alert listing and event creation
+3. **Workflow Automation** - Workflow configuration and execution
+4. **Role Management** - User and role assignment
+5. **Configuration** - Severities, types, statuses
+6. **Catalog** - Service catalog management
+
+**Design Pattern:** Each tool is a self-contained struct implementing the `Tool` interface.
+
+---
+
+### Layer 4: API Client Layer
+
+**Location**: `internal/incidentio/`
+
+**Responsibilities:**
+- HTTP request/response handling
+- Authentication (Bearer token)
+- Error parsing and transformation
+- Type definitions for API entities
+
+**Client Architecture:**
+```go
+type Client struct {
+    httpClient *http.Client
+    baseURL    string
+    apiKey     string
+}
+```
+
+**Request Pipeline:**
+```
+API Method → doRequest → HTTP Client → incident.io API
+                ↓
+           Error Handler
+                ↓
+        Response Parsing
+```
+
+**Features:**
+- 30-second timeout per request
+- TLS 1.2+ enforcement
+- Automatic error response parsing
+- Configurable base URL for testing
+
+---
+
+### Layer 5: Type Layer
+
+**Location**: `pkg/mcp/types.go`, `internal/incidentio/types.go`
+
+**Responsibilities:**
+- MCP protocol type definitions
+- incident.io API type definitions
+- JSON marshaling/unmarshaling
+
+**MCP Types:**
+```go
+type Message struct {
+    Jsonrpc string      `json:"jsonrpc"`
+    ID      interface{} `json:"id,omitempty"`
+    Method  string      `json:"method,omitempty"`
+    Params  interface{} `json:"params,omitempty"`
+    Result  interface{} `json:"result,omitempty"`
+    Error   *Error      `json:"error,omitempty"`
+}
+```
+
+**API Types:**
+- `Incident`, `Alert`, `Workflow`, `Action`
+- Request/Response structs for all operations
+- Shared types: `Severity`, `IncidentStatus`, `User`
+
+---
+
+## Component Design
+
+### Tool Registration System
+
+**Location**: `cmd/mcp-server/main.go:42-73`, `internal/server/server.go:59-118`
+
+**Pattern:** Registry pattern with lazy initialization
+
+```go
+func (s *Server) registerTools() {
+    client, err := incidentio.NewClient()
+    if err != nil {
+        return // No tools registered if client fails
+    }
+
+    s.tools["tool_name"] = NewToolConstructor(client)
+}
+```
+
+**Benefits:**
+- Centralized tool management
+- Easy to add new tools
+- Client dependency injection
+- Fail-safe if API key missing
+
+---
+
+### Enhanced Tool Pattern
+
+**Example**: `create_incident_enhanced.go`
+
+**Pattern:** Smart wrapper with automatic ID resolution
+
+```
+User Input (human names) → ID Lookup → API Call → Response
+```
+
+**Features:**
+- Accepts human-readable names ("high" instead of "01HXYZ...")
+- Automatic severity/type/status lookup
+- Graceful fallback to defaults
+- Better user experience than raw API
+
+**Tradeoff:** Additional API calls for lookups vs. better UX
+
+---
+
+### Validation Layer
+
+**Location**: `internal/tools/validation.go`
+
+**Pattern:** Shared validation utilities
+
+**Functions:**
+- Parameter presence validation
+- Type checking and coercion
+- Error message standardization
+- Context-rich error reporting
+
+**Example:**
+```go
+if id == "" {
+    return "", fmt.Errorf("incident_id parameter is required and must be a non-empty string. Received parameters: %+v", args)
+}
+```
+
+---
+
+## Data Flow
+
+### Tool Execution Flow
+
+```
+1. MCP Client sends tools/call message
+   ↓
+2. Server decodes JSON-RPC message
+   ↓
+3. Server validates message structure
+   ↓
+4. Server extracts tool name and arguments
+   ↓
+5. Server looks up tool in registry
+   ↓
+6. Tool validates input parameters
+   ↓
+7. Tool calls API client method
+   ↓
+8. API client makes HTTP request
+   ↓
+9. API client parses response/error
+   ↓
+10. Tool formats result as string
+   ↓
+11. Server wraps in MCP response
+   ↓
+12. Server encodes and writes to stdout
+```
+
+### Error Propagation
+
+```
+API Error → Client Error → Tool Error → Server Error → MCP Error Response
+```
+
+**Levels:**
+1. **API Level**: HTTP status codes, error response bodies
+2. **Client Level**: `ErrorResponse` struct parsing
+3. **Tool Level**: Business logic validation
+4. **Server Level**: JSON-RPC error codes
+5. **Protocol Level**: MCP error messages
+
+---
+
+## MCP Protocol Implementation
+
+### Protocol Version
+
+**Version**: `2024-11-05`
+
+**Capabilities:**
+```json
+{
+  "tools": {
+    "listChanged": false
+  }
+}
+```
+
+### Message Types
+
+**1. Initialize Request**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "initialize"
+}
+```
+
+**2. Initialize Response**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "2024-11-05",
+    "capabilities": {...},
+    "serverInfo": {
+      "name": "incidentio-mcp-server",
+      "version": "0.1.0"
+    }
+  }
+}
+```
+
+**3. Tools List Request**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 2,
+  "method": "tools/list"
+}
+```
+
+**4. Tool Call Request**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "method": "tools/call",
+  "params": {
+    "name": "get_incident",
+    "arguments": {
+      "incident_id": "INC-123"
+    }
+  }
+}
+```
+
+**5. Error Response**
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "error": {
+    "code": -32603,
+    "message": "Tool execution failed: incident not found"
+  }
+}
+```
+
+---
+
+## Design Patterns
+
+### 1. Interface Segregation
+
+**Tool Interface**: Small, focused interface with 4 methods
+- Enables easy testing with mocks
+- Clear contract for tool implementation
+- No unnecessary dependencies
+
+### 2. Dependency Injection
+
+**Client Injection**: Tools receive `*incidentio.Client` in constructor
+- Testability: Can inject mock clients
+- Flexibility: Can swap implementations
+- Decoupling: Tools don't create clients
+
+### 3. Factory Pattern
+
+**Tool Constructors**: `NewToolTool(client)` functions
+- Consistent initialization
+- Clear dependencies
+- Encapsulated setup logic
+
+### 4. Registry Pattern
+
+**Tool Registry**: `map[string]tools.Tool`
+- Dynamic tool lookup
+- Easy to extend
+- Centralized management
+
+### 5. Template Method
+
+**Tool Execution**: Common execute pattern
+- Validate input
+- Call API client
+- Format response
+- Handle errors
+
+### 6. Adapter Pattern
+
+**MCP Adapter**: Adapts incident.io API to MCP protocol
+- Protocol translation
+- Format conversion
+- Error transformation
+
+---
+
+## Testing Strategy
+
+### Unit Testing
+
+**Locations:**
+- `internal/incidentio/*_test.go`
+- `internal/tools/*_test.go`
+
+**Approach:**
+- Mock HTTP server for API client tests
+- Mock client for tool tests
+- Table-driven tests for input validation
+- Edge case coverage
+
+**Example:**
+```go
+func TestGetIncident(t *testing.T) {
+    server := httptest.NewServer(...)
+    client := &incidentio.Client{...}
+
+    tool := NewGetIncidentTool(client)
+    result, err := tool.Execute(args)
+
+    // Assertions
+}
+```
+
+### Integration Testing
+
+**Location**: `tests/`
+
+**Approach:**
+- Python scripts for E2E testing
+- Real API calls (requires API key)
+- Shell scripts for smoke tests
+- Docker-based testing environment
+
+**Test Types:**
+1. **API Tests**: Direct API client testing
+2. **Tool Tests**: Full tool execution flow
+3. **MCP Protocol Tests**: stdin/stdout communication
+
+---
+
+## Deployment Architecture
+
+### Deployment Options
+
+**1. Direct Binary Execution**
+```bash
+./start-mcp-server.sh
+```
+
+**2. Docker Container**
+```bash
+docker-compose up
+```
+
+**3. Claude Desktop Integration**
+```json
+{
+  "mcpServers": {
+    "incidentio": {
+      "command": "/path/to/start-mcp-server.sh",
+      "env": {
+        "INCIDENT_IO_API_KEY": "..."
+      }
+    }
+  }
+}
+```
+
+### Environment Configuration
+
+**Required:**
+- `INCIDENT_IO_API_KEY` - Authentication token
+
+**Optional:**
+- `INCIDENT_IO_BASE_URL` - Custom API endpoint
+- `MCP_DEBUG` - Debug logging
+- `INCIDENT_IO_DEBUG` - API client debug logging
+
+### Process Architecture
+
+```
+┌─────────────────────────────────┐
+│     MCP Client Process          │
+│                                 │
+│  ┌──────────────────────────┐  │
+│  │  Fork MCP Server         │  │
+│  │  (start-mcp-server.sh)   │  │
+│  └──────────┬───────────────┘  │
+│             │                   │
+│  ┌──────────▼───────────────┐  │
+│  │  stdin/stdout pipes      │  │
+│  └──────────────────────────┘  │
+└─────────────────────────────────┘
+              │
+              │ MCP Protocol
+              ▼
+┌─────────────────────────────────┐
+│    MCP Server Process           │
+│                                 │
+│  ┌──────────────────────────┐  │
+│  │  JSON-RPC 2.0 Handler    │  │
+│  └──────────┬───────────────┘  │
+│             │                   │
+│  ┌──────────▼───────────────┐  │
+│  │  Tool Registry           │  │
+│  └──────────┬───────────────┘  │
+│             │                   │
+│  ┌──────────▼───────────────┐  │
+│  │  HTTP Client             │  │
+│  └──────────────────────────┘  │
+└─────────────────────────────────┘
+              │
+              │ HTTPS
+              ▼
+┌─────────────────────────────────┐
+│     incident.io API V2          │
+└─────────────────────────────────┘
+```
+
+### Security Considerations
+
+1. **API Key Management**: Environment variables only, never hardcoded
+2. **TLS**: Minimum TLS 1.2 for API communication
+3. **Input Validation**: All tool inputs validated before use
+4. **Error Handling**: No sensitive data in error messages
+5. **Process Isolation**: Server runs as separate process
+
+### Scalability Considerations
+
+**Current Design:**
+- Stateless server (no session management)
+- Single process per client
+- No request queuing
+
+**Limitations:**
+- One concurrent request per server instance
+- No connection pooling
+- No rate limiting
+
+**Future Enhancements:**
+- Request concurrency with goroutines
+- Connection pooling for API calls
+- Built-in rate limiting
+- Metrics and monitoring
+
+---
+
+## Code Organization
+
+```
+incidentio-mcp/
+├── cmd/
+│   └── mcp-server/         # Entry point
+│       └── main.go
+├── internal/
+│   ├── incidentio/         # API client layer
+│   │   ├── client.go       # HTTP client
+│   │   ├── incidents.go    # Incident operations
+│   │   ├── alerts.go       # Alert operations
+│   │   ├── workflows.go    # Workflow operations
+│   │   └── types.go        # Type definitions
+│   ├── server/             # MCP server layer
+│   │   └── server.go       # Protocol handler
+│   └── tools/              # Tools layer
+│       ├── tool.go         # Tool interface
+│       ├── incidents.go    # Incident tools
+│       ├── alerts.go       # Alert tools
+│       └── validation.go   # Shared validation
+├── pkg/
+│   └── mcp/                # MCP protocol types
+│       └── types.go
+└── tests/                  # Integration tests
+```
+
+**Design Principles:**
+- `internal/` - Implementation details, not importable
+- `pkg/` - Public interfaces (though unused externally)
+- `cmd/` - Binary entry points
+- Clear separation of concerns
+- Dependency direction: cmd → internal → pkg
+
+---
+
+## Extension Points
+
+### Adding New Tools
+
+1. Create tool struct in `internal/tools/`
+2. Implement `Tool` interface
+3. Register in `registerTools()` function
+4. Add API client method if needed
+5. Write unit tests
+
+### Adding API Endpoints
+
+1. Define types in `internal/incidentio/types.go`
+2. Add client method in appropriate file
+3. Write client unit tests
+4. Create corresponding tool
+
+### Protocol Extensions
+
+1. Add new method handler in `server.go`
+2. Implement method logic
+3. Update protocol version if needed
+4. Document in ARCHITECTURE.md
+
+---
+
+## Performance Characteristics
+
+**Latency:**
+- Tool execution: ~50-500ms (depends on API)
+- Protocol overhead: <1ms
+- Total response time: API latency + ~10ms
+
+**Memory:**
+- Base process: ~10MB
+- Per request: ~1-2MB
+- No memory leaks (tested with long-running sessions)
+
+**Throughput:**
+- Sequential processing (by design)
+- Limited by API rate limits
+- No artificial throttling
+
+**Resource Usage:**
+- CPU: Minimal (<1% idle, <5% under load)
+- Network: Depends on tool usage
+- File Descriptors: 3 (stdin, stdout, stderr)
diff --git a/claudedocs/INDEX.md b/claudedocs/INDEX.md
new file mode 100644
index 0000000..f724ac7
--- /dev/null
+++ b/claudedocs/INDEX.md
@@ -0,0 +1,454 @@
+# incident.io MCP Server - Documentation Index
+
+Comprehensive documentation index for the incident.io MCP server project.
+
+## Quick Navigation
+
+| Documentation | Purpose | Audience |
+|---------------|---------|----------|
+| [API Reference](API_REFERENCE.md) | incident.io API client library documentation | Developers integrating the API client |
+| [Tools Reference](TOOLS_REFERENCE.md) | MCP tools documentation and usage patterns | MCP client users and developers |
+| [Architecture](ARCHITECTURE.md) | System design and technical architecture | Architects and senior developers |
+| [Quick Start](QUICK_START.md) | Get started quickly with common tasks | New users |
+
+---
+
+## Documentation by Role
+
+### For MCP Client Users
+
+**Goal**: Use the MCP server effectively with Claude or other MCP clients
+
+1. **Start Here**: [Quick Start Guide](QUICK_START.md)
+2. **Tool Reference**: [Tools Reference](TOOLS_REFERENCE.md)
+   - Learn available tools
+   - Understand parameters and responses
+   - See usage examples
+3. **Common Workflows**: [Tools Reference - Usage Patterns](TOOLS_REFERENCE.md#tool-usage-patterns)
+
+**Key Concepts:**
+- Tools are accessed through natural language via MCP clients
+- Tool names and parameters are consistent across all tools
+- Always use `incident_id` parameter (not `id` or `incidentId`)
+
+---
+
+### For Go Developers
+
+**Goal**: Extend the API client or understand implementation
+
+1. **Architecture Overview**: [Architecture Documentation](ARCHITECTURE.md)
+   - System layers and components
+   - Design patterns used
+   - Extension points
+2. **API Client**: [API Reference](API_REFERENCE.md)
+   - All API methods and types
+   - Error handling patterns
+   - HTTP client configuration
+3. **Code Structure**:
+   ```
+   internal/incidentio/     → API client implementation
+   internal/tools/          → MCP tool implementations
+   internal/server/         → MCP protocol handler
+   pkg/mcp/                 → MCP type definitions
+   ```
+
+**Development Workflow:**
+```bash
+# Run tests
+go test ./...
+
+# Build
+go build -o bin/mcp-server ./cmd/mcp-server
+
+# Format
+go fmt ./...
+
+# Lint (if available)
+golangci-lint run
+```
+
+---
+
+### For MCP Tool Developers
+
+**Goal**: Create new MCP tools or modify existing ones
+
+1. **Tool Interface**: [Architecture - Tools Layer](ARCHITECTURE.md#layer-3-tools-layer)
+2. **Tool Examples**: `internal/tools/incidents.go`, `internal/tools/alerts.go`
+3. **Adding New Tools**: [Architecture - Extension Points](ARCHITECTURE.md#adding-new-tools)
+
+**Tool Development Pattern:**
+```go
+// 1. Define tool struct
+type MyTool struct {
+    client *incidentio.Client
+}
+
+// 2. Implement Tool interface
+func (t *MyTool) Name() string { return "my_tool" }
+func (t *MyTool) Description() string { return "..." }
+func (t *MyTool) InputSchema() map[string]interface{} { ... }
+func (t *MyTool) Execute(args map[string]interface{}) (string, error) { ... }
+
+// 3. Register in server
+s.tools["my_tool"] = NewMyTool(client)
+```
+
+---
+
+### For System Architects
+
+**Goal**: Understand system design and make architectural decisions
+
+1. **System Overview**: [Architecture - System Overview](ARCHITECTURE.md#system-overview)
+2. **Layer Architecture**: [Architecture - Architecture Layers](ARCHITECTURE.md#architecture-layers)
+3. **Data Flow**: [Architecture - Data Flow](ARCHITECTURE.md#data-flow)
+4. **Design Patterns**: [Architecture - Design Patterns](ARCHITECTURE.md#design-patterns)
+5. **Deployment**: [Architecture - Deployment Architecture](ARCHITECTURE.md#deployment-architecture)
+
+**Key Design Decisions:**
+- **Layered Architecture**: Clear separation between protocol, tools, and API client
+- **Interface-Based Design**: Tool interface enables extensibility and testing
+- **Stateless Server**: Each request is independent, no session management
+- **stdio Communication**: MCP protocol over stdin/stdout for process isolation
+
+---
+
+## Documentation by Task
+
+### Getting Started
+
+1. [Installation and Setup](../README.md#-quick-start)
+2. [Configuration](../docs/CONFIGURATION.md)
+3. [First Tool Call](QUICK_START.md#your-first-tool-call)
+
+### Creating Incidents
+
+1. [Discover Available Options](QUICK_START.md#discovering-available-options)
+   - List severities
+   - List incident types
+   - List incident statuses
+2. [Create Basic Incident](TOOLS_REFERENCE.md#create_incident)
+3. [Create Smart Incident](TOOLS_REFERENCE.md#create_incident_smart) (with auto-ID resolution)
+4. [Post Status Updates](TOOLS_REFERENCE.md#create_incident_update)
+
+### Managing Alerts
+
+1. [List Alerts](TOOLS_REFERENCE.md#list_alerts)
+2. [View Alert Details](TOOLS_REFERENCE.md#get_alert)
+3. [Create Alert Events](TOOLS_REFERENCE.md#create_alert_event)
+4. [Configure Alert Routes](TOOLS_REFERENCE.md#create_alert_route)
+
+### Team Management
+
+1. [Find Users](TOOLS_REFERENCE.md#list_users)
+2. [View Available Roles](TOOLS_REFERENCE.md#list_available_incident_roles)
+3. [Assign Roles](TOOLS_REFERENCE.md#assign_incident_role)
+
+### Workflow Automation
+
+1. [List Workflows](TOOLS_REFERENCE.md#list_workflows)
+2. [View Workflow Details](TOOLS_REFERENCE.md#get_workflow)
+3. [Update Workflow](TOOLS_REFERENCE.md#update_workflow)
+
+### Catalog Management
+
+1. [View Catalog Types](TOOLS_REFERENCE.md#list_catalog_types)
+2. [List Catalog Entries](TOOLS_REFERENCE.md#list_catalog_entries)
+3. [Update Catalog Entries](TOOLS_REFERENCE.md#update_catalog_entry)
+
+---
+
+## API Coverage Matrix
+
+| API Category | Supported Operations | Documentation |
+|--------------|---------------------|---------------|
+| **Incidents** | List, Get, Create, Update | [API Reference](API_REFERENCE.md#incidents-api) |
+| **Incident Updates** | List, Get, Create, Delete | [API Reference](API_REFERENCE.md#incident-updates-api) |
+| **Incident Types** | List | [API Reference](API_REFERENCE.md#incident-types-api) |
+| **Alerts** | List, Get, List for Incident | [API Reference](API_REFERENCE.md#alerts-api) |
+| **Alert Routes** | List, Get, Create, Update | [API Reference](API_REFERENCE.md#alert-routes-api) |
+| **Alert Sources** | List | [API Reference](API_REFERENCE.md#alert-sources--events-api) |
+| **Alert Events** | Create | [API Reference](API_REFERENCE.md#alert-sources--events-api) |
+| **Workflows** | List, Get, Update | [API Reference](API_REFERENCE.md#workflows-api) |
+| **Actions** | List, Get | [API Reference](API_REFERENCE.md#actions-api) |
+| **Roles** | List, Assign | [API Reference](API_REFERENCE.md#roles--users-api) |
+| **Users** | List (with email filter) | [API Reference](API_REFERENCE.md#roles--users-api) |
+| **Severities** | List, Get | [API Reference](API_REFERENCE.md#severities-api) |
+| **Catalog** | List Types, List Entries, Update | [API Reference](API_REFERENCE.md#catalog-api) |
+
+---
+
+## Code Reference Index
+
+### Core Interfaces
+
+| Interface | Location | Purpose |
+|-----------|----------|---------|
+| `Tool` | `internal/tools/tool.go:3-8` | Base interface for all MCP tools |
+| `Client` | `internal/incidentio/client.go:20-24` | HTTP client for incident.io API |
+| `Message` | `pkg/mcp/types.go` | MCP protocol message structure |
+
+### Key Implementations
+
+| Component | Location | Description |
+|-----------|----------|-------------|
+| MCP Server | `cmd/mcp-server/main.go` | Main entry point and server lifecycle |
+| Server Handler | `internal/server/server.go` | MCP protocol message handling |
+| Tool Registry | `internal/server/server.go:59-118` | Tool registration system |
+| HTTP Client | `internal/incidentio/client.go:66-115` | HTTP request/response handling |
+
+### Tool Implementations
+
+| Tool Category | Location | Tools |
+|---------------|----------|-------|
+| Incident Tools | `internal/tools/incidents.go` | list_incidents, get_incident, create_incident, update_incident |
+| Enhanced Tools | `internal/tools/create_incident_enhanced.go` | create_incident_smart |
+| Alert Tools | `internal/tools/alerts.go` | list_alerts, get_alert, list_alerts_for_incident |
+| Alert Route Tools | `internal/tools/alert_routes.go` | list_alert_routes, get_alert_route, create_alert_route |
+| Workflow Tools | `internal/tools/workflows.go` | list_workflows, get_workflow, update_workflow |
+| Role Tools | `internal/tools/roles.go` | list_available_incident_roles, list_users, assign_incident_role |
+| Config Tools | `internal/tools/severities.go` | list_severities, get_severity |
+| Catalog Tools | `internal/tools/catalog.go` | list_catalog_types, list_catalog_entries, update_catalog_entry |
+
+---
+
+## Testing Index
+
+### Unit Tests
+
+| Test File | Coverage |
+|-----------|----------|
+| `internal/incidentio/client_test.go` | HTTP client functionality |
+| `internal/incidentio/incidents_test.go` | Incident API methods |
+| `internal/incidentio/workflows_test.go` | Workflow API methods |
+| `internal/incidentio/alert_routes_test.go` | Alert route API methods |
+| `internal/incidentio/alert_sources_test.go` | Alert source API methods |
+| `internal/incidentio/alert_events_test.go` | Alert event API methods |
+| `internal/tools/incidents_test.go` | Incident tools |
+| `internal/tools/create_incident_enhanced_test.go` | Enhanced incident creation |
+
+### Integration Tests
+
+| Test Script | Purpose |
+|-------------|---------|
+| `tests/test_api.sh` | Basic API connectivity |
+| `tests/test_endpoints.sh` | Endpoint availability |
+| `tests/test_mcp.py` | MCP protocol compliance |
+| `tests/test_create_incident.py` | Incident creation workflow |
+| `tests/test_severities.py` | Severity listing and lookup |
+
+---
+
+## Configuration Reference
+
+### Environment Variables
+
+| Variable | Required | Default | Purpose |
+|----------|----------|---------|---------|
+| `INCIDENT_IO_API_KEY` | Yes | - | Authentication token |
+| `INCIDENT_IO_BASE_URL` | No | `https://api.incident.io/v2` | API endpoint |
+| `MCP_DEBUG` | No | - | Enable debug logging |
+| `INCIDENT_IO_DEBUG` | No | - | Enable API client debug logging |
+
+### Claude Desktop Configuration
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "incidentio": {
+      "command": "/path/to/start-mcp-server.sh",
+      "env": {
+        "INCIDENT_IO_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+**Docker Alternative**:
+
+```json
+{
+  "mcpServers": {
+    "incidentio": {
+      "command": "docker-compose",
+      "args": ["-f", "/path/to/docker-compose.yml", "run", "--rm", "-T", "mcp-server"],
+      "env": {
+        "INCIDENT_IO_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+---
+
+## Troubleshooting Guide
+
+### Common Issues
+
+| Issue | Solution | Reference |
+|-------|----------|-----------|
+| 404 errors | Verify incident ID exists | [README - Troubleshooting](../README.md#common-issues) |
+| Authentication errors | Check API key validity | [Configuration](../docs/CONFIGURATION.md) |
+| Parameter errors | Use `incident_id` not `id` | [README - Troubleshooting](../README.md#common-issues) |
+| Tool not found | Verify tool registration | [Architecture - Tool Registration](ARCHITECTURE.md#tool-registration-system) |
+| API timeout | Check network and API status | [API Reference - HTTP Client](API_REFERENCE.md#http-client-configuration) |
+
+### Debug Mode
+
+```bash
+export MCP_DEBUG=1
+export INCIDENT_IO_DEBUG=1
+./start-mcp-server.sh
+```
+
+Logs to stderr for debugging without breaking MCP protocol.
+
+---
+
+## Related Documentation
+
+### Project Documentation
+
+- [README.md](../README.md) - Project overview and quick start
+- [CONTRIBUTING.md](../docs/CONTRIBUTING.md) - Contribution guidelines
+- [DEVELOPMENT.md](../docs/DEVELOPMENT.md) - Development setup and workflow
+- [TESTING.md](../docs/TESTING.md) - Testing guidelines
+- [DEPLOYMENT.md](../docs/DEPLOYMENT.md) - Deployment instructions
+- [CONFIGURATION.md](../docs/CONFIGURATION.md) - Configuration reference
+
+### External Resources
+
+- [Model Context Protocol Specification](https://modelcontextprotocol.io/)
+- [incident.io API V2 Documentation](https://api-docs.incident.io/)
+- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
+
+---
+
+## Version History
+
+### Current Version: 0.1.0
+
+**Features:**
+- Complete incident.io V2 API coverage
+- 35+ MCP tools
+- MCP protocol 2024-11-05 compliance
+- Docker support
+- Comprehensive test suite
+
+**Known Limitations:**
+- No connection pooling
+- No built-in rate limiting
+- Sequential request processing only
+- No metrics/monitoring
+
+**Roadmap:**
+- Concurrent request handling
+- Connection pooling
+- Built-in rate limiting
+- Metrics and observability
+- Additional workflow automation tools
+
+---
+
+## Documentation Maintenance
+
+### Documentation Structure
+
+```
+claudedocs/
+├── INDEX.md              # This file - navigation hub
+├── QUICK_START.md        # Getting started guide
+├── API_REFERENCE.md      # API client documentation
+├── TOOLS_REFERENCE.md    # MCP tools documentation
+└── ARCHITECTURE.md       # System architecture
+```
+
+### Update Guidelines
+
+When modifying the codebase:
+
+1. **New Tools**: Update TOOLS_REFERENCE.md and QUICK_START.md
+2. **API Changes**: Update API_REFERENCE.md
+3. **Architecture Changes**: Update ARCHITECTURE.md
+4. **New Features**: Update README.md and relevant guides
+5. **All Changes**: Update this INDEX.md if navigation changes
+
+### Documentation Standards
+
+- Use code references with `location:line_number` format
+- Include practical examples for all features
+- Maintain cross-references between documents
+- Keep table of contents updated
+- Use consistent terminology throughout
+
+---
+
+## Quick Reference Commands
+
+### Build and Run
+
+```bash
+# Build
+go build -o bin/mcp-server ./cmd/mcp-server
+
+# Run directly
+./start-mcp-server.sh
+
+# Run with Docker
+docker-compose up
+
+# Run tests
+go test ./...
+
+# Run specific test
+go test ./internal/tools/...
+```
+
+### Development
+
+```bash
+# Format code
+go fmt ./...
+
+# Vet code
+go vet ./...
+
+# Run linter
+golangci-lint run
+
+# Check test coverage
+go test -cover ./...
+```
+
+### Integration Testing
+
+```bash
+# API tests
+./tests/test_api.sh
+
+# Endpoint tests
+./tests/test_endpoints.sh
+
+# Python tests
+python tests/test_mcp.py
+```
+
+---
+
+## Support and Feedback
+
+- **Issues**: [GitHub Issues](https://github.com/incident-io/incidentio-mcp-golang/issues)
+- **Contributing**: See [CONTRIBUTING.md](../docs/CONTRIBUTING.md)
+- **Community**: Check the incident.io community forums
+
+---
+
+**Last Updated**: 2025-10-13
+**Documentation Version**: 1.0
+**Project Version**: 0.1.0
diff --git a/claudedocs/QUICK_START.md b/claudedocs/QUICK_START.md
new file mode 100644
index 0000000..11e5984
--- /dev/null
+++ b/claudedocs/QUICK_START.md
@@ -0,0 +1,534 @@
+# Quick Start Guide
+
+Get up and running with the incident.io MCP server quickly.
+
+## Prerequisites
+
+- Go 1.21 or later
+- incident.io account with API access
+- API key from incident.io dashboard
+- (Optional) Claude Desktop or another MCP client
+
+---
+
+## Installation
+
+### Option 1: Direct Binary
+
+```bash
+# Clone the repository
+git clone https://github.com/incident-io/incidentio-mcp-golang.git
+cd incidentio-mcp-golang
+
+# Set up environment
+cp .env.example .env
+# Edit .env and add your API key: INCIDENT_IO_API_KEY=your-key-here
+
+# Build
+go build -o bin/mcp-server ./cmd/mcp-server
+
+# Run
+./start-mcp-server.sh
+```
+
+### Option 2: Docker
+
+```bash
+# Clone the repository
+git clone https://github.com/incident-io/incidentio-mcp-golang.git
+cd incidentio-mcp-golang
+
+# Build Docker image
+docker-compose build
+
+# Run
+docker-compose up
+```
+
+---
+
+## Configuration
+
+### Claude Desktop Setup
+
+Add to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "incidentio": {
+      "command": "/absolute/path/to/incidentio-mcp-golang/start-mcp-server.sh",
+      "env": {
+        "INCIDENT_IO_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+**Docker Alternative**:
+
+```json
+{
+  "mcpServers": {
+    "incidentio": {
+      "command": "docker-compose",
+      "args": ["-f", "/absolute/path/to/docker-compose.yml", "run", "--rm", "-T", "mcp-server"],
+      "env": {
+        "INCIDENT_IO_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `INCIDENT_IO_API_KEY` | Yes | Your incident.io API key |
+| `INCIDENT_IO_BASE_URL` | No | Custom API endpoint (defaults to production) |
+| `MCP_DEBUG` | No | Enable debug logging (set to 1) |
+
+---
+
+## Your First Tool Call
+
+Once configured with Claude Desktop, you can use natural language:
+
+```
+"List all active incidents"
+```
+
+Claude will use the `list_incidents` tool with appropriate parameters.
+
+### Behind the Scenes
+
+What happens:
+1. Claude interprets your request
+2. Selects `list_incidents` tool
+3. Calls MCP server with parameters: `{"status": ["active"]}`
+4. Server calls incident.io API
+5. Results returned to Claude
+6. Claude presents information naturally
+
+---
+
+## Common Workflows
+
+### 1. Creating Your First Incident
+
+**Natural Language:**
+```
+"What severity levels are available?"
+"What incident types exist?"
+"Create a new incident called 'API Gateway Timeout' with high severity"
+```
+
+**What Happens:**
+1. `list_severities` - Discovers available severity options
+2. `list_incident_types` - Discovers incident type options
+3. `create_incident` - Creates incident with discovered IDs
+
+**Direct Tool Usage (if building your own MCP client):**
+
+```json
+// Step 1: List severities
+{
+  "tool": "list_severities"
+}
+
+// Step 2: Create incident
+{
+  "tool": "create_incident",
+  "arguments": {
+    "name": "API Gateway Timeout",
+    "summary": "Users experiencing 504 gateway timeout errors",
+    "severity_id": "01HXYZ...",
+    "incident_type_id": "01HXYZ...",
+    "incident_status_id": "01HXYZ..."
+  }
+}
+```
+
+### 2. Managing Existing Incidents
+
+**Natural Language:**
+```
+"Show me details for incident INC-123"
+"Update INC-123 summary to 'Issue resolved after cache flush'"
+"Post an update to INC-123 saying 'Investigating root cause'"
+```
+
+**Tools Used:**
+- `get_incident` - View incident details
+- `update_incident` - Modify incident properties
+- `create_incident_update` - Post status updates
+
+### 3. Team Collaboration
+
+**Natural Language:**
+```
+"Find user with email john.doe@company.com"
+"What incident roles are available?"
+"Assign John Doe as incident lead for INC-123"
+```
+
+**Tools Used:**
+- `list_users` with email filter
+- `list_available_incident_roles`
+- `assign_incident_role`
+
+### 4. Alert Management
+
+**Natural Language:**
+```
+"Show me all alerts for incident INC-123"
+"List all alert sources"
+"What alert routes are configured?"
+```
+
+**Tools Used:**
+- `list_alerts_for_incident`
+- `list_alert_sources`
+- `list_alert_routes`
+
+---
+
+## Discovering Available Options
+
+Before creating incidents, it's helpful to discover what options are available.
+
+### Severities
+
+```
+"What severities are available?"
+```
+
+**Tool**: `list_severities`
+
+**Response**: List of severities with IDs, names, descriptions, and ranks (lower rank = higher severity)
+
+### Incident Types
+
+```
+"What incident types exist?"
+```
+
+**Tool**: `list_incident_types`
+
+**Response**: List of incident types with IDs, names, and descriptions
+
+### Incident Statuses
+
+```
+"What incident statuses are there?"
+```
+
+**Tool**: `list_incident_statuses`
+
+**Response**: List of statuses like triage, active, resolved, closed
+
+### Users
+
+```
+"Find user with email jane@company.com"
+```
+
+**Tool**: `list_users` with email filter
+
+**Response**: User details including ID for role assignment
+
+### Roles
+
+```
+"What incident roles can be assigned?"
+```
+
+**Tool**: `list_available_incident_roles`
+
+**Response**: Available roles like Incident Lead, Communications Lead, etc.
+
+---
+
+## Common Patterns
+
+### Pattern 1: Full Incident Lifecycle
+
+```
+1. "Create incident: Database performance degradation, high severity"
+2. "Assign Alice as incident lead for INC-123"
+3. "Post update to INC-123: Investigating slow queries"
+4. "Update INC-123 severity to medium"
+5. "Post update to INC-123: Issue resolved, monitoring"
+6. "Close incident INC-123"
+```
+
+### Pattern 2: Alert Investigation
+
+```
+1. "List all active alerts"
+2. "Show details for alert ALT-456"
+3. "List alerts for incident INC-123"
+4. "Create incident from these alerts"
+```
+
+### Pattern 3: Workflow Management
+
+```
+1. "List all workflows"
+2. "Show details for workflow WF-789"
+3. "Update workflow WF-789 to enable it"
+```
+
+### Pattern 4: Catalog Updates
+
+```
+1. "List catalog types"
+2. "List all services in the catalog"
+3. "Update service 'payments-api' with new team information"
+```
+
+---
+
+## Tips and Best Practices
+
+### 1. Always Use Correct Parameter Names
+
+❌ **Wrong**: `"id": "INC-123"`
+✅ **Right**: `"incident_id": "INC-123"`
+
+The parameter is always `incident_id`, never just `id`.
+
+### 2. Discover Before Creating
+
+Before creating incidents, discover available options:
+- List severities first
+- List incident types first
+- List incident statuses first
+
+This ensures you use valid IDs.
+
+### 3. Use Smart Creation
+
+For easier incident creation, use `create_incident_smart` which accepts human-readable names:
+
+```json
+{
+  "tool": "create_incident_smart",
+  "arguments": {
+    "name": "Service Down",
+    "severity": "high",
+    "incident_type": "outage"
+  }
+}
+```
+
+The tool will automatically look up the correct IDs.
+
+### 4. Check Error Messages
+
+Error messages include helpful suggestions:
+
+```
+"Error: severity_id is required.
+Suggestion: Use list_severities to see available options."
+```
+
+Follow these suggestions to resolve issues quickly.
+
+### 5. Use Filtering
+
+Most list tools support filtering:
+
+```json
+{
+  "tool": "list_incidents",
+  "arguments": {
+    "status": ["active", "triage"],
+    "page_size": 50
+  }
+}
+```
+
+### 6. Pagination
+
+For large result sets, use `page_size` parameter:
+
+```json
+{
+  "tool": "list_incidents",
+  "arguments": {
+    "page_size": 100
+  }
+}
+```
+
+Maximum: 250 results per page.
+
+---
+
+## Troubleshooting
+
+### "Tool not found" Error
+
+**Cause**: Server failed to initialize due to missing API key
+
+**Solution**: Ensure `INCIDENT_IO_API_KEY` is set in environment
+
+```bash
+# Check if set
+echo $INCIDENT_IO_API_KEY
+
+# Set if missing
+export INCIDENT_IO_API_KEY="your-api-key"
+```
+
+### "incident_id parameter is required" Error
+
+**Cause**: Missing or incorrectly named parameter
+
+**Solution**: Use `incident_id`, not `id`:
+
+❌ `{"id": "INC-123"}`
+✅ `{"incident_id": "INC-123"}`
+
+### "404 Not Found" Error
+
+**Cause**: Incident ID doesn't exist
+
+**Solution**:
+1. Verify incident ID is correct
+2. Check if incident exists: `list_incidents`
+3. Ensure you have access permissions
+
+### "401 Unauthorized" Error
+
+**Cause**: Invalid or missing API key
+
+**Solution**:
+1. Verify API key is correct
+2. Check API key has proper permissions
+3. Regenerate API key if needed
+
+### "422 Validation Error"
+
+**Cause**: Missing required fields or invalid values
+
+**Solution**:
+1. Check error message for specific field
+2. Use list tools to discover valid values
+3. Follow suggestions in error message
+
+### Server Not Starting
+
+**Symptoms**: Claude shows "Server failed to start"
+
+**Debug Steps**:
+
+```bash
+# Enable debug mode
+export MCP_DEBUG=1
+export INCIDENT_IO_DEBUG=1
+
+# Run directly to see errors
+./start-mcp-server.sh
+```
+
+Check stderr output for specific error messages.
+
+---
+
+## Next Steps
+
+### Learn More
+
+- **[Tools Reference](TOOLS_REFERENCE.md)** - Complete tool documentation
+- **[API Reference](API_REFERENCE.md)** - API client library details
+- **[Architecture](ARCHITECTURE.md)** - System design and internals
+
+### Extend the Server
+
+- **Add New Tools**: See [Architecture - Extension Points](ARCHITECTURE.md#extension-points)
+- **Contribute**: See [CONTRIBUTING.md](../docs/CONTRIBUTING.md)
+- **Test**: See [TESTING.md](../docs/TESTING.md)
+
+### Advanced Usage
+
+- **Custom API Endpoints**: Set `INCIDENT_IO_BASE_URL` for testing
+- **Debug Logging**: Enable `MCP_DEBUG=1` for troubleshooting
+- **Docker Deployment**: See [DEPLOYMENT.md](../docs/DEPLOYMENT.md)
+
+---
+
+## Example: Complete Incident Workflow
+
+Here's a complete example workflow from creation to closure:
+
+### Step 1: Discover Options
+
+```
+User: "What severity levels and incident types are available?"
+```
+
+**Tools Called**:
+- `list_severities`
+- `list_incident_types`
+
+### Step 2: Create Incident
+
+```
+User: "Create a new incident: 'Payment API returning 500 errors' with high severity"
+```
+
+**Tool Called**: `create_incident`
+**Result**: Incident INC-123 created
+
+### Step 3: Assign Team
+
+```
+User: "Find user alice@company.com and assign her as incident lead for INC-123"
+```
+
+**Tools Called**:
+- `list_users` (with email filter)
+- `assign_incident_role`
+
+### Step 4: Monitor and Update
+
+```
+User: "Post update to INC-123: 'Identified database connection pool exhaustion as root cause'"
+```
+
+**Tool Called**: `create_incident_update`
+
+### Step 5: Resolve
+
+```
+User: "Post update to INC-123: 'Connection pool size increased, errors stopped. Monitoring for 30 minutes.'"
+```
+
+**Tool Called**: `create_incident_update`
+
+### Step 6: Close
+
+```
+User: "Close incident INC-123"
+```
+
+**Tool Called**: `close_incident`
+
+---
+
+## Getting Help
+
+- **Documentation**: Start with [INDEX.md](INDEX.md) for navigation
+- **Issues**: Report bugs at [GitHub Issues](https://github.com/incident-io/incidentio-mcp-golang/issues)
+- **Community**: incident.io community forums
+- **API Docs**: [incident.io API Documentation](https://api-docs.incident.io/)
+
+---
+
+**Ready to start?** Try creating your first incident with Claude or dive deeper into the [Tools Reference](TOOLS_REFERENCE.md)!
diff --git a/claudedocs/TOOLS_REFERENCE.md b/claudedocs/TOOLS_REFERENCE.md
new file mode 100644
index 0000000..e349ceb
--- /dev/null
+++ b/claudedocs/TOOLS_REFERENCE.md
@@ -0,0 +1,822 @@
+# MCP Tools Reference
+
+Complete reference for all MCP tools provided by the incident.io MCP server.
+
+## Table of Contents
+
+- [Tool Interface](#tool-interface)
+- [Incident Management Tools](#incident-management-tools)
+- [Incident Update Tools](#incident-update-tools)
+- [Alert Management Tools](#alert-management-tools)
+- [Alert Routing Tools](#alert-routing-tools)
+- [Workflow Tools](#workflow-tools)
+- [Action Tools](#action-tools)
+- [Role & User Tools](#role--user-tools)
+- [Configuration Tools](#configuration-tools)
+- [Catalog Tools](#catalog-tools)
+- [Tool Usage Patterns](#tool-usage-patterns)
+
+---
+
+## Tool Interface
+
+Location: `internal/tools/tool.go:3-8`
+
+All tools implement the `Tool` interface:
+
+```go
+type Tool interface {
+    Name() string
+    Description() string
+    InputSchema() map[string]interface{}
+    Execute(args map[string]interface{}) (string, error)
+}
+```
+
+**MCP Protocol:**
+- Tools are registered at server startup
+- Tool list available via `tools/list` method
+- Tool execution via `tools/call` method with JSON-RPC 2.0
+
+---
+
+## Incident Management Tools
+
+### list_incidents
+
+Location: `internal/tools/incidents.go:13-86`
+
+List incidents with optional filtering.
+
+**Parameters:**
+```json
+{
+  "page_size": 25,
+  "status": ["active", "triage"],
+  "severity": ["01HXYZ..."]
+}
+```
+
+**Example:**
+```
+List all active incidents with high severity
+```
+
+**Response:** JSON array of incident objects
+
+---
+
+### get_incident
+
+Location: `internal/tools/incidents.go:88-140`
+
+Get detailed information about a specific incident.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123"
+}
+```
+
+**Required:** `incident_id`
+
+**Error Handling:**
+- Validates `incident_id` is non-empty string
+- Returns detailed error with received parameters if validation fails
+- HTTP 404 if incident not found
+
+**Example:**
+```
+Get details for incident INC-123
+```
+
+---
+
+### create_incident
+
+Location: `internal/tools/incidents.go:142-284`
+
+Create a new incident with intelligent defaults and suggestions.
+
+**Parameters:**
+```json
+{
+  "name": "Database performance degradation",
+  "summary": "Users experiencing slow queries",
+  "severity_id": "01HXYZ...",
+  "incident_type_id": "01HXYZ...",
+  "incident_status_id": "01HXYZ...",
+  "mode": "standard",
+  "visibility": "public",
+  "slack_channel_name_override": "incident-db-perf"
+}
+```
+
+**Required:** `name`
+
+**Defaults:**
+- `mode`: "standard"
+- `visibility`: "public"
+
+**Smart Features:**
+- Automatic idempotency key generation: `mcp-{timestamp}-{name}`
+- Suggests using `list_severities` if `severity_id` missing
+- Suggests using `list_incident_types` if `incident_type_id` missing
+- Suggests using `list_incident_statuses` if `incident_status_id` missing
+- Includes suggestions in error messages when API validation fails
+
+**Example:**
+```
+Create a new incident called "API Gateway 500 errors" with high severity
+```
+
+---
+
+### create_incident_smart
+
+Location: `internal/tools/create_incident_enhanced.go`
+
+Enhanced incident creation with automatic ID resolution.
+
+**Parameters:**
+```json
+{
+  "name": "Service degradation",
+  "summary": "High error rates detected",
+  "severity": "high",
+  "incident_type": "service_issue",
+  "incident_status": "triage"
+}
+```
+
+**Features:**
+- Accepts human-readable names instead of IDs
+- Automatically looks up severity, type, and status IDs
+- Falls back to defaults if lookups fail
+- More user-friendly than `create_incident`
+
+---
+
+### update_incident
+
+Location: `internal/tools/incidents.go:286-379`
+
+Update an existing incident's properties.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "name": "Updated incident name",
+  "summary": "Updated summary",
+  "incident_status_id": "01HXYZ...",
+  "severity_id": "01HXYZ..."
+}
+```
+
+**Required:** `incident_id`
+**Requires:** At least one field to update
+
+**Validation:**
+- Ensures `incident_id` is non-empty
+- Validates at least one update field is provided
+
+**Example:**
+```
+Update incident INC-123 summary to "Issue resolved"
+```
+
+---
+
+### close_incident
+
+Location: `internal/tools/close_incident.go`
+
+Close an incident with proper workflow handling.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123"
+}
+```
+
+**Required:** `incident_id`
+
+**Behavior:**
+- Fetches incident statuses
+- Identifies "closed" status
+- Updates incident to closed state
+- Returns updated incident details
+
+**Example:**
+```
+Close incident INC-456
+```
+
+---
+
+### list_incident_statuses
+
+Location: `internal/tools/incident_statuses.go`
+
+List all available incident statuses.
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "incident_statuses": [
+    {
+      "id": "01HXYZ...",
+      "name": "Triage",
+      "category": "triage"
+    }
+  ]
+}
+```
+
+**Usage:** Call before creating/updating incidents to get valid status IDs
+
+---
+
+### list_incident_types
+
+Location: `internal/tools/incident_types.go`
+
+List all configured incident types.
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "incident_types": [
+    {
+      "id": "01HXYZ...",
+      "name": "Service Outage",
+      "description": "Complete service unavailability"
+    }
+  ]
+}
+```
+
+**Usage:** Call before creating incidents to get valid type IDs
+
+---
+
+## Incident Update Tools
+
+### list_incident_updates
+
+Location: `internal/tools/incident_updates.go`
+
+List all status updates for an incident.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "page_size": 25
+}
+```
+
+**Required:** `incident_id`
+
+---
+
+### get_incident_update
+
+Get a specific incident update.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "update_id": "01HXYZ..."
+}
+```
+
+**Required:** `incident_id`, `update_id`
+
+---
+
+### create_incident_update
+
+Post a status update to an incident.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "message": "Database queries have returned to normal latency"
+}
+```
+
+**Required:** `incident_id`, `message`
+
+**Example:**
+```
+Post update to INC-123: "Root cause identified, deploying fix"
+```
+
+---
+
+### delete_incident_update
+
+Remove an incident update.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "update_id": "01HXYZ..."
+}
+```
+
+**Required:** `incident_id`, `update_id`
+
+---
+
+## Alert Management Tools
+
+### list_alerts
+
+Location: `internal/tools/alerts.go`
+
+List all alerts with optional filtering.
+
+**Parameters:**
+```json
+{
+  "page_size": 50,
+  "status": ["firing"]
+}
+```
+
+---
+
+### get_alert
+
+Get details of a specific alert.
+
+**Parameters:**
+```json
+{
+  "alert_id": "01HXYZ..."
+}
+```
+
+**Required:** `alert_id`
+
+---
+
+### list_alerts_for_incident
+
+List all alerts associated with an incident.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123"
+}
+```
+
+**Required:** `incident_id`
+
+**Example:**
+```
+Show me all alerts for incident INC-123
+```
+
+---
+
+### create_alert_event
+
+Location: `internal/tools/alert_events.go`
+
+Create a new alert event from an alert source.
+
+**Parameters:**
+```json
+{
+  "alert_source_id": "01HXYZ...",
+  "payload": {
+    "title": "High CPU usage",
+    "severity": "warning",
+    "details": "CPU usage above 90%"
+  }
+}
+```
+
+**Required:** `alert_source_id`, `payload`
+
+---
+
+### list_alert_sources
+
+Location: `internal/tools/alert_sources.go`
+
+List all configured alert sources.
+
+**Parameters:** None
+
+**Usage:** Get alert source IDs for creating alert events
+
+---
+
+## Alert Routing Tools
+
+### list_alert_routes
+
+Location: `internal/tools/alert_routes.go`
+
+List all alert routing rules.
+
+**Parameters:**
+```json
+{
+  "page_size": 25
+}
+```
+
+---
+
+### get_alert_route
+
+Get details of a specific alert route.
+
+**Parameters:**
+```json
+{
+  "alert_route_id": "01HXYZ..."
+}
+```
+
+**Required:** `alert_route_id`
+
+---
+
+### create_alert_route
+
+Create a new alert routing rule.
+
+**Parameters:**
+```json
+{
+  "name": "Database Alerts",
+  "enabled": true,
+  "condition_groups": []
+}
+```
+
+**Required:** `name`
+
+---
+
+### update_alert_route
+
+Update an existing alert route.
+
+**Parameters:**
+```json
+{
+  "alert_route_id": "01HXYZ...",
+  "name": "Updated Route Name",
+  "enabled": false
+}
+```
+
+**Required:** `alert_route_id`
+
+---
+
+## Workflow Tools
+
+### list_workflows
+
+Location: `internal/tools/workflows.go`
+
+List all configured workflows.
+
+**Parameters:**
+```json
+{
+  "page_size": 25
+}
+```
+
+---
+
+### get_workflow
+
+Get details of a specific workflow.
+
+**Parameters:**
+```json
+{
+  "workflow_id": "01HXYZ..."
+}
+```
+
+**Required:** `workflow_id`
+
+---
+
+### update_workflow
+
+Update workflow configuration.
+
+**Parameters:**
+```json
+{
+  "workflow_id": "01HXYZ...",
+  "name": "Updated Workflow",
+  "enabled": true
+}
+```
+
+**Required:** `workflow_id`
+
+---
+
+## Action Tools
+
+### list_actions
+
+Location: `internal/tools/actions.go`
+
+List all workflow actions.
+
+**Parameters:**
+```json
+{
+  "page_size": 25,
+  "incident_id": "INC-123"
+}
+```
+
+---
+
+### get_action
+
+Get details of a specific action.
+
+**Parameters:**
+```json
+{
+  "action_id": "01HXYZ..."
+}
+```
+
+**Required:** `action_id`
+
+---
+
+## Role & User Tools
+
+### list_available_incident_roles
+
+Location: `internal/tools/roles.go`
+
+List all configured incident roles.
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "incident_roles": [
+    {
+      "id": "01HXYZ...",
+      "name": "Incident Lead",
+      "description": "Leads incident response"
+    }
+  ]
+}
+```
+
+---
+
+### list_users
+
+List organization users.
+
+**Parameters:**
+```json
+{
+  "page_size": 50,
+  "email": "user@example.com"
+}
+```
+
+**Features:**
+- Filter by email for user lookup
+- Pagination support
+
+**Example:**
+```
+Find user with email john.doe@example.com
+```
+
+---
+
+### assign_incident_role
+
+Assign a role to a user for an incident.
+
+**Parameters:**
+```json
+{
+  "incident_id": "INC-123",
+  "role_id": "01HXYZ...",
+  "user_id": "01HXYZ..."
+}
+```
+
+**Required:** `incident_id`, `role_id`, `user_id`
+
+**Example:**
+```
+Assign Jane Smith as incident lead for INC-123
+```
+
+---
+
+## Configuration Tools
+
+### list_severities
+
+Location: `internal/tools/severities.go`
+
+List all severity levels.
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "severities": [
+    {
+      "id": "01HXYZ...",
+      "name": "Critical",
+      "description": "Service completely unavailable",
+      "rank": 1
+    }
+  ]
+}
+```
+
+**Note:** Lower rank = higher severity
+
+---
+
+### get_severity
+
+Get details of a specific severity.
+
+**Parameters:**
+```json
+{
+  "severity_id": "01HXYZ..."
+}
+```
+
+**Required:** `severity_id`
+
+---
+
+## Catalog Tools
+
+### list_catalog_types
+
+Location: `internal/tools/catalog.go`
+
+List all catalog types (services, teams, etc.).
+
+**Parameters:** None
+
+**Response:**
+```json
+{
+  "catalog_types": [
+    {
+      "id": "01HXYZ...",
+      "name": "Services",
+      "type_name": "Service"
+    }
+  ]
+}
+```
+
+---
+
+### list_catalog_entries
+
+List entries for a specific catalog type.
+
+**Parameters:**
+```json
+{
+  "catalog_type_id": "01HXYZ...",
+  "page_size": 50
+}
+```
+
+**Required:** `catalog_type_id`
+
+**Example:**
+```
+List all services in the catalog
+```
+
+---
+
+### update_catalog_entry
+
+Update a catalog entry's attributes.
+
+**Parameters:**
+```json
+{
+  "catalog_type_id": "01HXYZ...",
+  "entry_id": "01HXYZ...",
+  "attribute_values": {}
+}
+```
+
+**Required:** `catalog_type_id`, `entry_id`
+
+---
+
+## Tool Usage Patterns
+
+### Discovery Pattern
+
+Before creating incidents, discover available options:
+
+```
+1. list_severities → Get severity IDs
+2. list_incident_types → Get type IDs
+3. list_incident_statuses → Get status IDs
+4. create_incident → Create with discovered IDs
+```
+
+### Role Assignment Pattern
+
+```
+1. list_users with email filter → Find user
+2. list_available_incident_roles → Get role options
+3. assign_incident_role → Assign user to incident
+```
+
+### Alert Routing Pattern
+
+```
+1. list_alert_sources → Get source IDs
+2. list_alert_routes → Check existing routes
+3. create_alert_route → Create new routing rule
+```
+
+### Incident Lifecycle Pattern
+
+```
+1. create_incident → Create new incident
+2. create_incident_update → Post status updates
+3. assign_incident_role → Assign team members
+4. close_incident → Close when resolved
+```
+
+### Error Recovery Pattern
+
+When tool execution fails:
+
+```
+1. Check error message for missing IDs
+2. Call suggested list_* tools
+3. Retry with correct IDs
+```
+
+---
+
+## Validation Layer
+
+Location: `internal/tools/validation.go`
+
+Common validation utilities used across tools:
+
+- **String validation**: Non-empty string checks
+- **ID validation**: Format and existence validation
+- **Parameter validation**: Required field enforcement
+- **Error formatting**: Consistent error messages with context
+
+**Pattern:**
+```go
+if id == "" {
+    return "", fmt.Errorf("incident_id parameter is required and must be a non-empty string. Received parameters: %+v", args)
+}
+```
+
+This provides clear feedback to users about what went wrong and what was received.