Skip to main content
Glama
Petra Security MCP Server

Petra Security MCP Server

by WYRE-AI

petra_list_incidents

Read-onlyIdempotent

Lists Microsoft 365 identity-compromise incidents such as account takeovers and BEC, newest first, with filters for tenant, user, date, and live attacker status.

Instructions

List Microsoft 365 identity-compromise incidents Petra detected (account takeovers, BEC), newest first: compromised user, occurred/created time, remediation status, whether the attacker is still live, dwell time, and the phishing email that led to it. Omit tenantId to search every tenant in the organization. Petra only alerts on real compromises.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "petra_list_incidents"
  }
}

Input Schema

NameRequiredDescriptionDefault
limitNoMaximum incidents Petra returns (1-500, default 100). Local filters below apply after this limit.
liveOnlyNoOnly incidents where the attacker is still live (isLive=true).
tenantIdNoLimit to one tenant. Petra tenant ID (from petra_list_tenants, or the app.petrasecurity.com/tenant/<id> URL) or the Microsoft tenant ID; Petra resolves either.
startDateNoOnly incidents created on or after this ISO 8601 date or date-time (e.g. 2026-03-01).
remediationStatusNoOnly incidents with this remediationStatus (e.g. REMEDIATED, REMEDIATED_PRIOR_TO_ONBOARDING). Filtered locally, case-insensitive.
userPrincipalNameNoOnly incidents for this user (UPN or mail, case-insensitive). Filtered locally.
includePhishingEmailNoInclude the phishingEmail details block. Defaults to true; set false for a compact list.

Schema Changelog

Changes observed during successful MCP inspections.

  1. First observedv0.1.0

TDQS

A3.9/5.0
Behavior4/5

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

Annotations already declare readOnlyHint, idempotentHint, destructiveHint=false and openWorldHint, so the safety profile is covered. The description adds real behavioral context beyond them: results are ordered newest first, omitting tenantId fans out across every tenant in the organization, and only confirmed compromises are surfaced. It stops short of describing pagination/truncation behavior or volume expectations.

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?

Two sentences, front-loaded with the core action and followed by the returned fields and the cross-tenant default. The field enumeration is dense but each item earns its place by telling the agent what it will receive.

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

Completeness4/5

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

With no output schema, the description usefully compensates by listing the returned fields, and annotations plus full schema coverage handle safety and parameters. The remaining gap is operational detail such as result volume, pagination beyond the limit cap, or what happens when the limit truncates before local filters apply.

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

Parameters4/5

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

Schema coverage is 100%, so the baseline is 3, but the description adds a default behavior the schema does not state: omitting tenantId searches every tenant in the organization. It also frames the filterable concepts (liveness, remediation status, dwell time) that the parameters map onto, giving the agent a mental model beyond raw field descriptions.

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

Purpose4/5

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

The description names a specific verb and resource ('List Microsoft 365 identity-compromise incidents Petra detected') and enumerates the fields returned (compromised user, times, remediation status, liveness, dwell time, phishing email), so an agent knows exactly what comes back. It also scopes the data ('account takeovers, BEC', 'Petra only alerts on real compromises'), which implicitly separates it from failed-attack style siblings, but it never names an alternative tool outright.

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

Usage Guidelines3/5

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

Usage is only implied through the return-field list and the 'omit tenantId to search every tenant' hint. There is no explicit statement of when to call this versus petra_get_incident (single incident) or petra_get_failed_attacks, and no prerequisites or exclusions are given.

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