entraadm-mcp

directory_audits

Retrieve directory audit logs to see who performed admin actions on users (block/unblock, password reset, role changes) and when. Helps distinguish handled from open cases.

Instructions

Who did what to the directory, and when -- the operator-side counterpart to signin_logs.

Every admin action against a user object (block/unblock, password reset, role assignment, attribute edits) appears here, naming the actor (initiated_by) and the affected object(s) (target_resources). This is the record a manual "unblock and reset" intervention -- like the one that closed the 2026-08-21 case this server exists to shorten -- leaves behind; it is how a later triage can tell "already handled by a human" from "still open".

user, when given, matches audits where that account is either the initiator or a target resource. Graph's directoryAudits endpoint only supports server-side $filter on the initiator (initiatedBy/user/userPrincipalName), not on targetResources, so this fetches the full time window and matches both sides client-side -- a window with many unrelated admin actions can need a larger max_pages budget than signin_logs/signin_failure_stats to find one specific user's audits; capped=true warns when that budget ran out before the window was fully scanned.

Read-only (AuditLog.Read.All application permission, or -- for azure-cli auth -- the Reports Reader directory role). Entra ID retains directory audit logs for 30 days, same as sign-in logs.

Time-bounded: the scan stops after ENTRAADM_DEADLINE seconds (default 45) and returns what it has with capped=true. Over several days the log is dominated by device-registration noise ("Update device"), so pass category (for example UserManagement, RoleManagement, GroupManagement, ApplicationManagement) to have Graph filter server-side; that keeps a multi-day window inside the budget.

Args: category: Only this Graph audit category (letters only; default: all). user: Restrict to audits naming this userPrincipalName as actor or target (default: all). hours: How far back to look, clamped to [1, 720] (30 days). top: Maximum records to return, clamped to [1, 500]. max_pages: Page budget (default: ENTRAADM_MAX_PAGES_DEFAULT).

Input Schema

TableJSON Schema

Name	Required	Description	Default
`top`	No
`user`	No
`hours`	No
`category`	No
`max_pages`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.1.0Oct 2, 2026

addedInput schema / properties / category

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Category"
+}

First observedv0.1.0Aug 24, 2026

TDQS

A4.9/5.0

Behavior5/5

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

With no annotations present, the description carries the full behavioral burden and does so: read-only, required AuditLog.Read.All application permission or Reports Reader role for azure-cli auth, 30-day Entra ID retention, a 45s ENTRAADM_DEADLINE scan cap returning partial results with capped=true, and the important client-side vs. server-side filter distinction (only initiatedBy supports $filter). This is well beyond what any structured field supplies.

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

Conciseness4/5

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

Front-loaded with the core 'who did what to the directory, and when' framing, and the Args block is dense and useful. It is longer than strictly necessary, though -- the aside about the 2026-08-21 case this server exists to shorten adds narrative color rather than invocation-relevant information.

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?

No output schema, no annotations, and a scan-heavy tool with a page budget and timeout, so the description has to be self-sufficient -- and it is. It covers return-relevant fields (initiated_by, target_resources, capped), permissions, retention window, and the operational tradeoff of narrowing by category, leaving no gap an agent would need filled before calling it.

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 description coverage is 0%, so the description must compensate fully and it does: every one of the 5 args is documented with meaning plus constraints (hours clamped to [1,720], top clamped to [1,500], category letters-only, max_pages default reference, user matches either actor or target). The user param's dual actor/target semantics in particular is only knowable from the prose.

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?

Names a specific resource (directory audits) and states exactly what it captures: admin actions against user objects (block/unblock, password reset, role assignment, attribute edits), with actor and target fields. It explicitly positions itself as the 'operator-side counterpart to signin_logs,' so an agent can separate it from the sibling sign-in tools without opening a schema.

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?

Gives explicit routing guidance: use this for admin/intervention history rather than sign-in events, and pass category (e.g. UserManagement) to keep multi-day windows within budget. It also names the sibling tools it shares a page budget model with and states the condition under which a larger max_pages is needed (many unrelated admin actions in-window).

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

Deploy Server

directory_audits

Instructions

Input Schema

Schema Changelog

TDQS

Other Tools