Fix: List Incidents Severity Filter and Enhanced Tool Documentation

[apetti1920]

Summary

This PR fixes a bug where the list_incidents tool's severity filter was not working, and significantly enhances the tool's documentation to guide proper usage, particularly around severity filtering workflows.

Problem Statement

Issue 1: Severity Filter Not Working

The list_incidents tool was accepting a severity parameter but not actually filtering incidents by severity. When attempting to filter by severity name (e.g., ["sev_1"]), all incidents within the page_size limit were being returned instead of only those matching the specified severity.

Root Cause: The implementation was using the incorrect API parameter name. The code was sending severity as the query parameter, but the incident.io API v2 requires severity[one_of] for filtering by specific severity IDs.

Issue 2: Insufficient Tool Documentation

The tool description was too brief ("List incidents from incident.io with optional filters") and didn't provide adequate guidance on:

• The proper workflow for filtering by severity
• The requirement to use severity IDs rather than names
• The need to call list_severities first to discover valid IDs
• How multiple filters combine (OR logic)

This lack of clarity could lead to confusion, especially for AI agents that rely on tool descriptions for proper usage.

Changes Made

1. Core Bug Fix: API Parameter Correction

File: /internal/incidentio/incidents.go

Fixed the severity filter to use the correct incident.io API parameter:

// BEFORE (Lines 43, 66)
params.Add("severity", severity)
baseParams.Add("severity", severity)

// AFTER
params.Add("severity[one_of]", severity)
baseParams.Add("severity[one_of]", severity)

Why severity[one_of]?

According to the incident.io API v2 documentation, the list incidents endpoint uses structured parameter names with operators:

• severity[one_of] - Filters incidents matching ANY of the provided severity IDs (OR logic)
• severity[lte] - Filters incidents with severity less than or equal to specified value

The [one_of] operator is essential because:

1. It tells the API to use OR logic when multiple IDs are provided
2. It distinguishes from other potential severity operators
3. It's the standard pattern the API uses for multi-value filters

Using just severity was ignored by the API, resulting in no filtering.

2. Enhanced Tool Description

File: /internal/tools/incidents.go - ListIncidentsTool.Description()

Replaced the brief description with a comprehensive multi-section guide:

New Description Structure:

• Summary: One-line overview of the tool's purpose
• USAGE WORKFLOW: 4-step process for using severity filtering correctly
• PARAMETERS: Detailed explanation of each parameter
• EXAMPLES: Concrete usage examples with actual JSON syntax
• IMPORTANT: Critical warnings about common mistakes

Key Additions:

USAGE WORKFLOW:
1. To filter by severity, first call 'list_severities' to get available severity IDs
2. Use the severity ID (not the name) in the 'severity' parameter
3. Multiple severity IDs can be provided to match any of them (OR logic)
4. Status filters can be combined with severity filters

Why This Matters:

• Discovery Pattern: AI agents learn they must call list_severities BEFORE using severity filters
• ID vs Name: Prevents the common mistake of using severity names like "Critical" instead of IDs like "sev_1"
• Workflow Clarity: Step-by-step instructions ensure correct tool chaining
• Error Prevention: Explicit guidance reduces failed API calls

3. Enhanced Parameter Descriptions

File: /internal/tools/incidents.go - ListIncidentsTool.InputSchema()

Updated all three parameter descriptions with detailed guidance:
Rationale:

• Explicit Requirements: States exactly what format is expected (IDs, not names)
• Discovery Guidance: Directs to call list_severities tool first
• Examples: Provides concrete syntax for clarity
• Logic Explanation: Clarifies OR behavior for multiple values
• Common Mistakes: Warns about ID vs name confusion