fix: enhance API error diagnostics and tool documentation

- Improve error visibility by reading and returning full Flashduty API error messages.
- Use io.LimitReader (4KB) when reading response bodies to prevent potential OOM.
- Enrich tool descriptions with specific parameter constraints (lengths, ranges, regex).
- Provide more actionable error guidance for time range and pagination limits.

Author: ysyneu

pkg/flashduty/changes.go

@@ -20,9 +20,13 @@ that may be correlated with incidents.
 **Parameters:**
 - change_ids (optional): Comma-separated change IDs for direct lookup
 - channel_id (optional): Filter by collaboration space ID
-- start_time, end_time (optional): Unix timestamp range
+- start_time, end_time (optional): Unix timestamp in seconds.
+  **Time constraints:**
+  - start_time must be less than end_time
+  - Time range (end_time - start_time) must not exceed 31 days (2678400 seconds)
+  - If not specified, defaults to last 1 hour
 - type (optional): Filter by change type
-- limit (optional): Max results (default 20)
+- limit (optional): Max results (1-100, default 20)
 
 **Returns:**
 - Change records with enriched channel and creator names`
@@ -87,7 +91,7 @@ func QueryChanges(getClient GetFlashdutyClientFn, t translations.TranslationHelp
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API failed with status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {

pkg/flashduty/channels.go

@@ -15,11 +15,12 @@ import (
 const queryChannelsDescription = `Query collaboration spaces (channels).
 
 **Parameters:**
-- channel_ids (optional): Comma-separated channel IDs for direct lookup
-- name (optional): Search by channel name
+- channel_ids (optional): Comma-separated channel IDs for direct lookup (max 1000)
+- name (optional): Search by channel name (case-insensitive substring match)
 
 **Returns:**
-- Channel list with team information`
+- Channel list with team information
+- When listing all channels, returns up to 100 results`
 
 // QueryChannels creates a tool to query channels
 func QueryChannels(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -76,7 +77,7 @@ func QueryChannels(getClient GetFlashdutyClientFn, t translations.TranslationHel
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {
@@ -157,7 +158,7 @@ func QueryEscalationRules(getClient GetFlashdutyClientFn, t translations.Transla
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {

pkg/flashduty/client.go

@@ -130,7 +130,8 @@ func sanitizeError(err error) string {
 // parseResponse parses the HTTP response into the given interface.
 // Note: caller is responsible for closing resp.Body.
 func parseResponse(resp *http.Response, v interface{}) error {
-	body, err := io.ReadAll(resp.Body)
+	// Limit reading to 4KB to prevent potential OOM
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 4096))
 	if err != nil {
 		return fmt.Errorf("failed to read response body: %w", err)
 	}
@@ -148,6 +149,20 @@ func parseResponse(resp *http.Response, v interface{}) error {
 	return nil
 }
 
+// handleAPIError reads the response body and returns a detailed error message.
+// This function should be called when resp.StatusCode != http.StatusOK.
+// It returns the full response body which contains request_id for debugging.
+func handleAPIError(resp *http.Response) error {
+	// Limit reading to 4KB to prevent potential OOM with unexpected large response bodies
+	body, err := io.ReadAll(io.LimitReader(resp.Body, 4096))
+	if err != nil {
+		return fmt.Errorf("API request failed with HTTP status %d (failed to read response: %v)", resp.StatusCode, err)
+	}
+
+	// Return full response body for better debugging (contains request_id, error code, message)
+	return fmt.Errorf("API request failed with HTTP status %d: %s", resp.StatusCode, string(body))
+}
+
 // FlashdutyResponse represents the standard Flashduty API response structure
 type FlashdutyResponse struct {
 	Error *DutyError  `json:"error,omitempty"`

pkg/flashduty/enrichment.go

@@ -31,7 +31,7 @@ func (c *Client) fetchIncidentTimeline(ctx context.Context, incidentID string) (
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("timeline API request failed with HTTP status %d", resp.StatusCode)
+		return nil, handleAPIError(resp)
 	}
 
 	var result struct {
@@ -69,7 +69,7 @@ func (c *Client) fetchIncidentAlerts(ctx context.Context, incidentID string, lim
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, 0, fmt.Errorf("alerts API request failed with HTTP status %d", resp.StatusCode)
+		return nil, 0, handleAPIError(resp)
 	}
 
 	var result struct {
@@ -144,7 +144,7 @@ func (c *Client) fetchPersonInfos(ctx context.Context, personIDs []int64) (map[i
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("person API request failed with HTTP status %d", resp.StatusCode)
+		return nil, handleAPIError(resp)
 	}
 
 	var result struct {
@@ -214,7 +214,7 @@ func (c *Client) fetchChannelInfos(ctx context.Context, channelIDs []int64) (map
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("channel API request failed with HTTP status %d", resp.StatusCode)
+		return nil, handleAPIError(resp)
 	}
 
 	var result struct {

pkg/flashduty/fields.go

@@ -18,14 +18,18 @@ Use this tool to discover available fields before updating incidents.
 
 **Parameters:**
 - field_ids (optional): Comma-separated field IDs for direct lookup
-- field_name (optional): Search by field name
+- field_name (optional): Search by exact field name (field_name must match regexp: ^[a-z][a-z0-9_]*$)
 
 **Returns:**
 - Field definitions including:
   - field_type: checkbox, multi_select, single_select, text
   - value_type: string, bool, float
   - options: available values for select fields
-  - default_value: default value if set`
+  - default_value: default value if set
+
+**Notes:**
+- Maximum 15 custom fields allowed per account
+- Returns all fields (no pagination needed)`
 
 // QueryFields creates a tool to query custom field definitions
 func QueryFields(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -54,7 +58,7 @@ func QueryFields(getClient GetFlashdutyClientFn, t translations.TranslationHelpe
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API failed with status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {

pkg/flashduty/incidents.go

@@ -37,7 +37,12 @@ Returns complete incident information including:
 - progress (optional): Filter by status - Triggered, Processing, Closed
 - severity (optional): Filter by severity - Info, Warning, Critical
 - channel_id (optional): Filter by collaboration space ID
-- start_time, end_time (optional): Unix timestamp range (required if no incident_ids)
+- start_time, end_time (optional): Unix timestamp in seconds. Required if no incident_ids.
+  **Time constraints:**
+  - start_time must be less than end_time
+  - Time range (end_time - start_time) must not exceed 31 days (2678400 seconds)
+  - end_time must be within the data retention period (account-specific, typically 365 days)
+  - If you get a time range error, use more recent timestamps (e.g., last 7-30 days from now)
 - title (optional): Title keyword search
 - limit (optional): Max results (default 20)
 - include_alerts (optional): Include alerts preview (default true)
@@ -342,7 +347,7 @@ func (c *Client) fetchIncidentsByIDs(ctx context.Context, incidentIDs []string)
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("API request failed with HTTP status %d", resp.StatusCode)
+		return nil, handleAPIError(resp)
 	}
 
 	var result struct {
@@ -392,7 +397,7 @@ func (c *Client) fetchIncidentsByFilters(ctx context.Context, progress, severity
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return nil, fmt.Errorf("API request failed with HTTP status %d", resp.StatusCode)
+		return nil, handleAPIError(resp)
 	}
 
 	var result struct {
@@ -416,10 +421,10 @@ func (c *Client) fetchIncidentsByFilters(ctx context.Context, progress, severity
 const createIncidentDescription = `Create a new incident in Flashduty.
 
 **Parameters:**
-- title (required): Incident title
+- title (required): Incident title (3-200 characters)
 - severity (required): Info, Warning, or Critical
 - channel_id (optional): Collaboration space ID
-- description (optional): Incident description
+- description (optional): Incident description (max 6144 characters)
 - assigned_to (optional): Comma-separated person IDs to assign
 
 **Returns:**
@@ -500,14 +505,15 @@ const updateIncidentDescription = `Update an existing incident.
 
 **Parameters:**
 - incident_id (required): Incident ID to update
-- title (optional): New title
-- description (optional): New description
+- title (optional): New title (3-200 characters)
+- description (optional): New description (max 6144 characters)
 - severity (optional): New severity (Info, Warning, Critical)
 - custom_fields (optional): JSON object of custom field updates, e.g. {"field_name": "value"}
 
 **Notes:**
 - Only provided fields will be updated
-- Use query_fields to discover available custom fields`
+- Use query_fields to discover available custom fields
+- Custom field names must match regexp: ^[a-z][a-z0-9_]*$`
 
 // UpdateIncident creates a tool to update an incident
 func UpdateIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -627,7 +633,7 @@ func (c *Client) updateIncidentField(ctx context.Context, incidentID, endpoint,
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("API request failed with HTTP status %d", resp.StatusCode)
+		return handleAPIError(resp)
 	}
 
 	var result FlashdutyResponse
@@ -655,7 +661,7 @@ func (c *Client) updateCustomField(ctx context.Context, incidentID, fieldName st
 	defer func() { _ = resp.Body.Close() }()
 
 	if resp.StatusCode != http.StatusOK {
-		return fmt.Errorf("API request failed with HTTP status %d", resp.StatusCode)
+		return handleAPIError(resp)
 	}
 
 	var result FlashdutyResponse
@@ -713,7 +719,7 @@ func AckIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelpe
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result FlashdutyResponse
@@ -776,7 +782,7 @@ func CloseIncident(getClient GetFlashdutyClientFn, t translations.TranslationHel
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result FlashdutyResponse
@@ -847,7 +853,7 @@ func ListSimilarIncidents(getClient GetFlashdutyClientFn, t translations.Transla
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {

pkg/flashduty/statuspage.go

@@ -47,7 +47,7 @@ func QueryStatusPages(getClient GetFlashdutyClientFn, t translations.Translation
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API failed with status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {
@@ -141,7 +141,9 @@ const listStatusChangesDescription = `List active change events (incidents/maint
 - type (required): Change type - "incident" or "maintenance"
 
 **Returns:**
-- List of active change events (non-resolved/completed)`
+- List of active change events (non-resolved/completed)
+- For incidents: returns those with status investigating/identified/monitoring (not resolved)
+- For maintenances: returns those with status scheduled/ongoing (not completed)`
 
 // ListStatusChanges creates a tool to list status page changes
 func ListStatusChanges(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -181,7 +183,7 @@ func ListStatusChanges(getClient GetFlashdutyClientFn, t translations.Translatio
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API failed with status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {
@@ -216,15 +218,19 @@ const createStatusIncidentDescription = `Create a new incident on a status page.
 
 **Parameters:**
 - page_id (required): Status page ID
-- title (required): Incident title
-- message (optional): Initial update message describing the incident
+- title (required): Incident title (max 255 characters)
+- message (optional): Initial update message describing the incident (required for the incident description)
 - status (optional): Status - investigating, identified, monitoring, resolved (default: investigating)
 - affected_components (optional): Comma-separated component IDs with status, format: "id1:degraded,id2:partial_outage"
-  - Component statuses: operational, degraded, partial_outage, full_outage
+  - Component statuses for incidents: degraded, partial_outage, full_outage
+  - At least one component change is required
 - notify_subscribers (optional): Whether to notify subscribers (default: true)
 
 **Returns:**
-- Created change event ID`
+- Created change event ID
+
+**Notes:**
+- The message/description field is required for creating an incident`
 
 // CreateStatusIncident creates a tool to create status page incident
 func CreateStatusIncident(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -340,17 +346,19 @@ const createChangeTimelineDescription = `Add a timeline update to a status page
 - page_id (required): Status page ID
 - change_id (required): Change event ID to update
 - message (required): Update message describing the change
-- at (optional): Timestamp for the update (Unix timestamp, default: now)
-- status (optional): New status - investigating, identified, monitoring, resolved
+- at (optional): Timestamp for the update (Unix timestamp in seconds, default: now)
+- status (optional): New status for incidents - investigating, identified, monitoring, resolved
+  - For maintenances use: scheduled, ongoing, completed
 - component_changes (optional): JSON array of component status changes, e.g. [{"component_id":"xxx","status":"degraded"}]
+  - Component statuses: operational, degraded, partial_outage, full_outage
 
 **Use cases:**
 - Post investigation updates
 - Mark incident as resolved
 - Update affected components
 
 **Returns:**
-- Created timeline entry ID`
+- Success confirmation`
 
 // CreateChangeTimeline creates a tool to add timeline entry to status change
 func CreateChangeTimeline(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {

pkg/flashduty/users.go

@@ -21,7 +21,8 @@ const queryMembersDescription = `Query members (users) in the account.
 - email (optional): Search by email
 
 **Returns:**
-- Member list with ID, name, email, and team memberships`
+- Member list with ID, name, email, and team memberships
+- When listing members, returns up to 100 results per page (default limit)`
 
 // QueryMembers creates a tool to query members
 func QueryMembers(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -91,7 +92,7 @@ func QueryMembers(getClient GetFlashdutyClientFn, t translations.TranslationHelp
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result MemberListResponse
@@ -123,7 +124,8 @@ const queryTeamsDescription = `Query teams in the account.
 - name (optional): Search by team name
 
 **Returns:**
-- Team list with members (names and emails)`
+- Team list with members (names and emails)
+- When listing teams, returns up to 20 results per page (default limit, max 100)`
 
 // QueryTeams creates a tool to query teams
 func QueryTeams(getClient GetFlashdutyClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
@@ -162,7 +164,7 @@ func QueryTeams(getClient GetFlashdutyClientFn, t translations.TranslationHelper
 				defer func() { _ = resp.Body.Close() }()
 
 				if resp.StatusCode != http.StatusOK {
-					return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+					return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 				}
 
 				var result FlashdutyResponse
@@ -192,7 +194,7 @@ func QueryTeams(getClient GetFlashdutyClientFn, t translations.TranslationHelper
 			defer func() { _ = resp.Body.Close() }()
 
 			if resp.StatusCode != http.StatusOK {
-				return mcp.NewToolResultError(fmt.Sprintf("API request failed with HTTP status %d", resp.StatusCode)), nil
+				return mcp.NewToolResultError(handleAPIError(resp).Error()), nil
 			}
 
 			var result struct {