list_incidents
Retrieve and filter ServiceNow incidents by assigned user, category, state, or search query. Manage pagination with limit and offset parameters for efficient incident tracking.
Instructions
List incidents from ServiceNow
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Implementation Reference
- The core handler function for the 'list_incidents' tool. Queries the ServiceNow 'incident' table API with pagination and optional filters (state, assigned_to, category, query), processes the response to handle reference fields, and returns a structured dictionary of incidents.def list_incidents( config: ServerConfig, auth_manager: AuthManager, params: ListIncidentsParams, ) -> dict: """ List incidents from ServiceNow. Args: config: Server configuration. auth_manager: Authentication manager. params: Parameters for listing incidents. Returns: Dictionary with list of incidents. """ api_url = f"{config.api_url}/table/incident" # Build query parameters query_params = { "sysparm_limit": params.limit, "sysparm_offset": params.offset, "sysparm_display_value": "true", "sysparm_exclude_reference_link": "true", } # Add filters filters = [] if params.state: filters.append(f"state={params.state}") if params.assigned_to: filters.append(f"assigned_to={params.assigned_to}") if params.category: filters.append(f"category={params.category}") if params.query: filters.append(f"short_descriptionLIKE{params.query}^ORdescriptionLIKE{params.query}") if filters: query_params["sysparm_query"] = "^".join(filters) # Make request try: response = requests.get( api_url, params=query_params, headers=auth_manager.get_headers(), timeout=config.timeout, ) response.raise_for_status() data = response.json() incidents = [] for incident_data in data.get("result", []): # Handle assigned_to field which could be a string or a dictionary assigned_to = incident_data.get("assigned_to") if isinstance(assigned_to, dict): assigned_to = assigned_to.get("display_value") incident = { "sys_id": incident_data.get("sys_id"), "number": incident_data.get("number"), "short_description": incident_data.get("short_description"), "description": incident_data.get("description"), "state": incident_data.get("state"), "priority": incident_data.get("priority"), "assigned_to": assigned_to, "category": incident_data.get("category"), "subcategory": incident_data.get("subcategory"), "created_on": incident_data.get("sys_created_on"), "updated_on": incident_data.get("sys_updated_on"), } incidents.append(incident) return { "success": True, "message": f"Found {len(incidents)} incidents", "incidents": incidents } except requests.RequestException as e: logger.error(f"Failed to list incidents: {e}") return { "success": False, "message": f"Failed to list incidents: {str(e)}", "incidents": [] }
- Pydantic model defining the input schema for the list_incidents tool, including pagination (limit, offset) and optional filters.class ListIncidentsParams(BaseModel): """Parameters for listing incidents.""" limit: int = Field(10, description="Maximum number of incidents to return") offset: int = Field(0, description="Offset for pagination") state: Optional[str] = Field(None, description="Filter by incident state") assigned_to: Optional[str] = Field(None, description="Filter by assigned user") category: Optional[str] = Field(None, description="Filter by category") query: Optional[str] = Field(None, description="Search query for incidents")
- src/servicenow_mcp/utils/tool_utils.py:396-402 (registration)Registers the 'list_incidents' tool in the central get_tool_definitions() function's dictionary, specifying the handler function alias, input schema, return type hint, description, and serialization method ('json')."list_incidents": ( list_incidents_tool, ListIncidentsParams, str, # Expects JSON string "List incidents from ServiceNow", "json", # Tool returns list/dict, needs JSON dump ),
- src/servicenow_mcp/tools/__init__.py:42-49 (registration)Imports list_incidents from incident_tools.py into the tools package namespace, making it available for export via __all__.from servicenow_mcp.tools.incident_tools import ( add_comment, create_incident, list_incidents, resolve_incident, update_incident, get_incident_by_number, )
- src/servicenow_mcp/utils/tool_utils.py:134-135 (registration)Imports the list_incidents handler as list_incidents_tool alias for use in tool definitions.list_incidents as list_incidents_tool, )