Skip to main content
Glama
Sentinel-One

Purple AI MCP Server

Official
by Sentinel-One

search_alerts

Search alerts using filters on severity, status, analyst verdict, date range, and more. Returns filtered alert lists with pagination support.

Instructions

Search alerts using advanced filters and criteria.

If a user is asking a "how many" type query, set the "first" field to 1 - "totalCount" is returned for any query.

Args: filters: JSON string containing an array of filter objects (optional). Each filter object must have: - fieldId: String field name (use flattened camelCase names below) - filterType: One of the supported filter types below - isNegated: Optional boolean to negate the filter (default: false)

        Common Field Names (flattened camelCase):
        - Core: "id", "severity", "status", "alertName", "detectedAt", "createdAt"
        - Analysis: "analystVerdict", "assigneeUserId", "assigneeFullName", "alertNoteExists"
        - Context: "storylineId", "description"

        Filter Types and Required Keys:

        String Filters (for severity, status, analystVerdict, etc.):
        - "string_equals": Exact match. Requires "value" key.
          Example: {"fieldId": "severity", "filterType": "string_equals", "value": "CRITICAL"}
        - "string_in": Match any of multiple values. Requires "values" key (list).
          Example: {"fieldId": "status", "filterType": "string_in", "values": ["NEW", "IN_PROGRESS"]}

        Boolean Filters (for alertNoteExists, etc.):
        - "boolean_equals": Exact match. Requires "value" key.
          Example: {"fieldId": "alertNoteExists", "filterType": "boolean_equals", "value": true}
        - "boolean_in": Match any of multiple values. Requires "values" key (list).
          Example: {"fieldId": "alertNoteExists", "filterType": "boolean_in", "values": [true, false]}

        Long Filters (for numeric IDs like assigneeUserId):
        - "long_equals": Exact match. Requires "value" key.
          Example: {"fieldId": "assigneeUserId", "filterType": "long_equals", "value": 123}
        - "long_in": Match any of multiple values. Requires "values" key (list).
          Example: {"fieldId": "assigneeUserId", "filterType": "long_in", "values": [1, 2, 3]}

        DateTime Filters (for detectedAt, createdAt):
        - "datetime_range": Range match using UNIX timestamps in milliseconds (UTC). Requires "start" and/or "end" keys.
          Optional: "startInclusive", "endInclusive" (default: true)

          IMPORTANT: All datetimes in the Alert API are in UTC timezone.
          You MUST use the iso_to_unix_timestamp tool to convert ISO 8601 datetime strings
          to UNIX timestamps (milliseconds) before using them in datetime filters.

          IMPORTANT: Unless the user specifies a field to query a DateTime on, use createdAt.

          The iso_to_unix_timestamp tool handles timezone conversion automatically.
          Provide datetimes in the user's preferred timezone (e.g., "2024-10-30T08:00:00-04:00" for Eastern Time)
          and the tool will convert to UTC milliseconds for the API.

          Example workflow:
          1. Call iso_to_unix_timestamp("2024-10-30T08:00:00-04:00") -> returns "1730289600000" (UTC)
          2. Use result in filter: {"fieldId": "createdAt", "filterType": "datetime_range", "start": 1730289600000}

          Example: {"fieldId": "createdAt", "filterType": "datetime_range", "start": 1730289600000}

        Fulltext Search (for alertName, id, storylineId):
        - "fulltext": Text search with case-insensitive substring matching. Requires "values" key (list).
          Example: {"fieldId": "alertName", "filterType": "fulltext", "values": ["malware", "threat"]}

        Limits:
        - Maximum 50 filters per request
        - Maximum 100 values in "values" arrays

first: Number of alerts to retrieve (1-100, default: 10).
after: Cursor for pagination (optional).
view_type: Filter by assignment - ALL, ASSIGNED_TO_ME, UNASSIGNED, MY_TEAM (default: ALL).
fields: Optional JSON string containing an array of field names to return.
        If not specified, returns all default fields (including dataSources).
        See list_alerts for available fields and dataSources behavior.

        IMPORTANT - dataSources field behavior:
        - When fields=None (default): dataSources is INCLUDED automatically
        - When fields is provided: dataSources is ONLY included if explicitly requested
          Example: '["id", "severity", "dataSources"]'

Performance Note: When paging through many results, use fields='["id"]' for intermediate pages to conserve context window space. Use totalCount to gauge result set size.

Returns: Filtered list of alerts in JSON format.

Raises: RuntimeError: If there's an error searching alerts. ValueError: If parameters are invalid.

Examples: CORRECT: filters=[ {"fieldId": "severity", "filterType": "string_in", "values": ["CRITICAL", "HIGH"]}, {"fieldId": "status", "filterType": "string_equals", "value": "NEW"}, {"fieldId": "alertNoteExists", "filterType": "boolean_equals", "value": false} ]

WRONG:
filters=[
  {"fieldId": "severity", "filterType": "EQUALS", "value": "CRITICAL"},  # Use "string_equals"
  {"fieldId": "status.value", "filterType": "string_equals", "value": "NEW"}  # Use "status" not "status.value"
]

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
filtersNo
firstNo
afterNo
view_typeNoALL
fieldsNo

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
resultYes
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavior: returns filtered list, raises RuntimeError/ValueError, default values, pagination via after cursor, totalCount behavior when first=1, and performance implications of fields. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but well-structured with clear sections (summary, Args, Performance Note, Returns, Raises, Examples). Every sentence adds value, and the details are necessary given the complexity of filtering. Front-loaded with the core purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (5 parameters, nested filters), the description covers all necessary aspects: usage, parameter details, examples, error handling, and references to sibling tools. The presence of an output schema means return value details are not required, but the description still mentions the return format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description compensates comprehensively. It explains each parameter in detail: filters (field names, filter types, required keys, examples), first (range and default), after (cursor), view_type (enum values), and fields (JSON string, dataSources behavior). Includes both correct and wrong examples.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Search alerts using advanced filters and criteria.' The verb 'search' with 'advanced filters' distinguishes it from sibling tools like list_alerts, which likely provides a simpler listing. The tool's specific function is immediately apparent.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Extensive guidelines are provided: when to use the 'first' field for count queries, when to use fields for performance, and explicit instructions for datetime conversion using the sibling iso_to_unix_timestamp tool. It also includes correct and incorrect examples, helping the agent avoid common mistakes.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Sentinel-One/purple-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server