Petra Security MCP Server

petra_get_failed_attacks

Read-onlyIdempotent

Retrieve blocked (failed) attack summaries for a tenant, including totals, origin countries, daily attack-type breakdowns, and most-targeted users; defaults to the last 30 days.

Instructions

Get the BLOCKED (failed) attack summary for one tenant: total count, counts by origin country, a daily breakdown by attack type (e.g. PASSWORD_SPRAY, LEGACY_AUTH), and the most-targeted users with the countries their attackers came from. Defaults to the last 30 days. Petra rate-limits this route heavily, so results are cached for 5 minutes.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "tenantId": "<tenantId>"
    },
    "name": "petra_get_failed_attacks"
  }
}

Input Schema

Name	Required	Description
`endDate`	No	End of the window, ISO 8601 date or date-time. Defaults to now.
`tenantId`	Yes	Petra tenant ID (from petra_list_tenants, or the app.petrasecurity.com/tenant/<id> URL) or the Microsoft tenant ID; Petra resolves either.
`startDate`	No	Start of the window, ISO 8601 date or date-time. Defaults to 30 days before endDate.

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 13, 2026

TDQS

A4/5.0

Behavior4/5

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

Annotations already declare read-only, idempotent, non-destructive behavior, so the safety profile is covered. The description adds genuinely non-obvious context the annotations can't convey: the route is heavily rate-limited and results are cached for 5 minutes, which tells the agent that data may lag and that calling in a tight loop is unproductive.

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, both dense: the first defines the payload contents, the second delivers the operational caveats. No filler, no restating of the tool name, and the most decision-relevant facts (what you get, then caching/rate limits) are front-loaded.

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 carries the return-shape burden and does so by naming each aggregate returned. Rate-limit and cache behavior are disclosed, and the time-window defaults are covered by the schema. Only error/failure modes and whether results are paginated are unaddressed, which is minor for a summary endpoint.

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

Parameters3/5

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

Schema coverage is 100% and each parameter already documents defaults (startDate defaults to 30 days before endDate, endDate to now, tenantId accepts Petra or Microsoft tenant IDs). The description only restates the 30-day default, adding no format or resolution detail beyond what the schema says, so the baseline 3 applies.

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?

States a specific verb and resource ('Get the BLOCKED (failed) attack summary for one tenant') and enumerates exactly what comes back: total count, counts by origin country, daily breakdown by attack type with named examples (PASSWORD_SPRAY, LEGACY_AUTH), and most-targeted users with attacker countries. An agent can tell this apart from petra_get_incident or petra_list_incidents without opening another schema.

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?

The description establishes scope ('for one tenant') and a default window ('last 30 days'), which implies when the tool applies. However, it never says when to reach for this instead of the sibling incident tools, nor any exclusion such as whether it covers blocked-only vs allowed traffic beyond the 'BLOCKED (failed)' framing.

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

Deploy Server