entraadm-mcp

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

With no annotations, the description carries the full burden and does so thoroughly: it discloses status states, done/error semantics, paging behavior, capped and records_truncated meanings, Graph record-limit behavior, omitted auditData details, and 403 missing_permission handling.

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

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

The description is long, but the length is earned by the tool's complexity: status polling, paging, truncation, permissions, and four undocumented schema parameters. It is front-loaded with the core purpose and uses bullets to structure the return details cleanly.

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

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

Given no annotations, no output schema, and 0% schema description coverage, the description provides everything an agent needs: return structure, status semantics, error and truncation behavior, tenant scoping, and parameter meanings. Nothing material appears missing.

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

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

Schema description coverage is 0%, but the description compensates by documenting every parameter: query_id as the GUID from audit_log_search_start, top clamped to [1, 500], max_pages as the records page budget with an environment default, and tenant as a section name, domain, or tenant id with default behavior.

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

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

The description states a specific resource and operation: it returns the status and, once finished, summarized records of an audit search started by audit_log_search_start. It explicitly ties itself to the sibling start tool, making its role distinct and immediately clear.

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

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

It gives explicit polling guidance: while status is notStarted or running, call again in a minute or two; once succeeded, records are returned. It also explains failure statuses, unknown IDs, tenant scoping, and permission behavior, leaving little ambiguity about when and how to use it.

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

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

No annotations exist, and the description fully carries the burden: it discloses the side effect (a saved audit search object is created in the Purview audit search page, but no directory/mailbox/file data changes), the async multi-minute latency, rate-limit behavior (429 surfaces as rate_limited and is not retried), the required permission plus service-scoped alternatives, 403 as missing_permission, and the tri-state meaning of the created flag including the ambiguous null case.

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

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

Front-loaded with purpose and the required follow-up call before diving into side effects and permissions, with an Args block for per-parameter detail. It is long, but nearly every sentence carries information an agent needs given zero schema documentation; the investigative framing in the second paragraph is the only somewhat expendable part.

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

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

Given 11 parameters, no annotations, no output schema and 0% schema coverage, the definition supplies everything needed to invoke correctly: return value (query_id), polling protocol, error-to-flag mappings, permission requirements, and a filter-combination rule (AND). Nothing material is missing.

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

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, and it documents all 11 parameters with semantics the names do not convey: hours is clamped to [1, 4320] and ignored when start is set, start/end require ISO 8601 with offset, keyword matches workload content (auditData) rather than indexed properties and caps at 256 chars, tenant falls back to the domain-claiming tenant, and record_types/operations/service come with concrete value examples.

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

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

Opens with a specific verb+resource ('Start a Microsoft Purview audit log search') and immediately scopes the workloads (OneDrive/SharePoint, Exchange, Entra). It is clearly separable from siblings like signin_logs and audit_log_search_result, the latter named explicitly as the consumer of this tool's output.

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

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

Explicitly states when this applies ('the follow-up to a confirmed takeover: the sign-in log shows which resources a session obtained tokens for, this shows what it then did') and gives the exact follow-up procedure: call audit_log_search_result with the returned query_id and same tenant until done is true. It also states the precondition that at least one filter beyond the window is required, so a whole-tenant sweep is impossible.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: it declares read-only behavior, required permissions, optional IdentityRiskyUser.Read.All, dependency on ENTRAADM_SITES_INI and ENTRAADM_HOME_COUNTRIES, deadline/capping semantics, and the lower-bound caveat when capped=true. It also explains that unavailable Microsoft risk data must not be read as 'no risky users,' which is exactly the kind of behavioral context an agent needs.

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

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

The description is long, but it is front-loaded and structurally organized around findings, counts, limitations, and Args. Most detail earns its place given the complexity and lack of annotations/output schema, though some explanatory repetition keeps it below maximally concise.

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

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

There is no output schema, yet the description thoroughly explains the return structure: spray_breaches, foreign_successes, microsoft_risky_users, counts, capping flags, severity logic, and availability failure shapes. It also covers permissions, environment dependencies, and scan limitations, leaving little ambiguity for an agent invoking it.

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

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

Schema description coverage is 0%, but the Args section documents all four parameters: hours with clamping range, tenant as section name or domain, min_spray_users with default and minimum, and max_pages with its environment-variable default. This fully compensates for the bare input schema.

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

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

The opening sentence states the specific resource and outcome: accounts probably taken over from one walk of the sign-in log. It also distinguishes itself from the sibling signin_failure_stats as the success-side counterpart, so an agent can route correctly without opening the schema.

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

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

The description clearly frames the tool as the success-side counterpart to signin_failure_stats and explains the investigative context, including that it walks the interactive sign-in log. It does not explicitly say when not to use it versus signin_success_stats or signin_logs, so it falls short of full when/when-not guidance.

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

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

With no annotations, the description carries the full burden and does so: it discloses per-section graceful degradation on permission failure, the shared call-budget splitting across tenants, that results are synchronous (unlike the job+poll sibling) with a timeout risk, and what shape the return payload takes. These are non-obvious operational traits an agent could not infer from the schema.

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

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

Front-loaded with the one-sentence summary, and nearly every paragraph carries operational value. It is somewhat long and includes repo-internal roadmap/CLAUDE.md references that don't help an agent decide or invoke, which keeps it short of a 5.

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

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

For a 3-param aggregator with no output schema and no annotations, the description is thorough: it describes the return shape (compact summary plus top-5 lists), the multi-tenant top-level/tenant keys, budget allocation, and failure modes. An agent has everything needed to call it correctly and interpret the result.

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

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

Schema coverage is 0%, so the description must compensate, and it does for all three params: hours is clamped to [1,720], max_pages is a page budget passed to both sections with a named default, and samples is flagged as currently unused. The only softness is that max_pages' default is given as an env-var name rather than a resolved value, but the semantics are still clear.

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

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

Opens with a specific verb+resource framing ('One-call morning-patrol summary') and enumerates exactly which data it aggregates (M365 service health, sign-in failures, spray suspects, admin actions). It explicitly names the four sibling tools it combines, so an agent can distinguish it from calling those tools individually.

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

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

Explicitly steers away from the obvious alternative: it says Azure VM backup is deliberately excluded and that the agent should call vm_backup_status separately, with a stated reason (ARM fan-out exhausting the shared budget). It also explains the multi-tenant case and the deadline=0 tradeoff, giving clear when-to-use and when-not-to-use context.

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

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

With no annotations present the description carries the full burden and does so thoroughly: read-only, required permission (AuditLog.Read.All or Reports Reader role), 30-day retention, a hard scan deadline (ENTRAADM_DEADLINE, default 45s) that returns partial results with `capped=true`, and the important caveat that Graph only server-filters on the initiator so `user` matching is client-side and can silently miss records if the page budget runs out. This is exactly the behavioral context an agent needs before calling.

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

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

The purpose and the key operational caveats are front-loaded, and the Args block is dense and useful. Some narrative framing ('like the one that closed the 2026-08-21 case this server exists to shorten') is atmospheric rather than operational and slightly inflates the length of an otherwise tight definition.

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

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

For a 6-parameter, zero-annotation, no-output-schema tool, the description covers everything material: what it returns implicitly (audit records with actor and targets), how to know results are truncated, permission and auth prerequisites, retention limits, and the performance trade-off of client-side user matching. Nothing an agent needs to call it correctly is missing.

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

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

Schema coverage is 0% — the schema only has titles and defaults — so the description must compensate, and the Args block does: it defines clamp ranges for `hours` [1,720] and `top` [1,500], explains that `user` matches either actor or target side, that `category` is letters-only and server-side, and that `tenant` accepts a config section name or a domain. That is substantive meaning beyond the schema.

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

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

Opens with a specific verb+resource framing ('Who did what to the directory, and when') and immediately positions itself as 'the operator-side counterpart to signin_logs.' It enumerates the exact event types captured (block/unblock, password reset, role assignment, attribute edits) and the key fields (initiated_by, target_resources), so an agent can distinguish it from every sibling without reading the schema.

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

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

Gives concrete selection conditions: pass `category` for multi-day windows to avoid device-registration noise, raise `max_pages` when filtering by `user` because target-side matching is client-side, and use the sibling tools for sign-in rather than admin activity. It never explicitly states a 'do not use this when...' exclusion, which is the only gap.

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

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

With no annotations, the description carries the full burden and does so well: it declares read-only access, required permissions, partial degradation of sign_in_activity, license-capping behavior, on-premises sync semantics, and how nonexistent accounts return found=false rather than an error.

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

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

The description is long but well front-loaded and organized around the key triage decision points. Some details, such as the SKU page-budget mechanism, are verbose, though they remain relevant because no output schema exists to explain those return fields.

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

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

Given no annotations, no output schema, and zero schema description coverage, the description supplies the behavioral, permission, and return-shape context an agent needs. It covers the main failure mode, degraded fields, and the exact-match requirement for the primary identifier.

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

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

Schema coverage is 0%, but the description fully documents both parameters beyond the schema titles. It explains that upn must be an exact userPrincipalName, and it describes tenant's purpose with concrete cases such as onmicrosoft.com, #EXT#, and B2B guest sign-ins.

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

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

The description states a specific resource and scope: an account's identity/lifecycle state, and positions it as the first check in triage. It distinguishes itself from signin_logs by explicitly referencing that sibling for the AADSTS50126 sign-in pattern.

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

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

It gives a clear primary use case (first thing to check on triage) and a stopping condition when account_enabled=false, plus a common pattern tying it to signin_logs. However, it does not explicitly name when other sibling tools such as get_user_auth_methods would be preferable.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only status, the exact permission (UserAuthenticationMethod.Read.All), and a real operational constraint — app-only auth only, degrading to a permission error under azure-cli. It also pre-empts a common failure mode by stating that a nonexistent account returns {found: false} rather than an error, matching get_user's contract.

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

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

The key claim (MFA registered or not) is front-loaded in the first two lines, followed by the precise mfa_registered definition, the not-found contract, and the auth caveat. The password-exclusion paragraph is slightly belabored but earns its place by preventing a misread of the count.

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

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

No output schema and no annotations exist, and the description covers the negative case's return shape, the permission model, and the auth-mode limitation. It does not sketch the shape of a successful result (the list of registered methods), which leaves a small gap for a tool whose whole purpose is enumerating them.

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

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

Schema coverage is 0%, so the description must document both parameters. The tenant argument gets rich treatment — what it overrides (the domain-claiming tenant), accepted forms (section name, domain, tenant id), and the scenarios that require it. The upn argument is only glossed as 'the account's userPrincipalName', which is adequate but adds little.

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

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

Opens with a specific verb+resource ('Registered authentication methods for one account') and immediately frames the practical question it answers ('is MFA actually set up?'). This is clearly distinguishable from sibling get_user, which returns account attributes rather than auth method registrations.

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

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

The MFA-coverage framing plus the 'password is excluded from the count' note tells an agent exactly what question this tool answers, and the tenant argument is scoped with concrete cases (onmicrosoft.com, #EXT#, B2B guest sign-ins in host tenant). It stops short of naming an alternative tool or an explicit when-not-to-use condition.

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

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

With no annotations, the description carries the full burden and does so: it states 'Read-only', explains how 'status' is derived from the two probe outcomes, documents the per-tenant call-budget/deadline trade-off, the one-hour Identity Protection cache, and that a configured-but-broken sites file caps status at degraded. It even explains why the ARM probe runs last under its own budget (tool-call timeout avoidance) — behavior an agent cannot infer from schema or annotations.

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

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

It is front-loaded with a clear one-line summary and organized by return key, but at roughly 450 words for a zero-parameter probe it is bloated with design rationale ('a fabricated diagnosis, since Graph plainly *is* reachable', 'azure-identity is synchronous') that does not help an agent decide or call correctly.

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

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

No output schema and no annotations exist, so the description must document returns — and it covers status semantics, per-tenant nesting, sites, identity_protection, home_countries and arm in detail. Gaps remain: the contents of the top-level 'service' and 'version' keys, and the shape of 'detail' messages, are never described.

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

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

Zero parameters, so the baseline of 4 applies; nothing in the schema needs elaboration beyond the environment variables (ENTRAADM_CONFIG, ENTRAADM_SITES_INI, ENTRAADM_DEADLINE, ENTRAADM_HOME_COUNTRIES) the description helpfully names as implicit inputs.

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

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

The first sentence names the specific verb and output ('Fleet-standard health probe: service/version/status plus two independent Graph probes'), so an agent knows exactly what it returns. It does not, however, distinguish itself from the sibling 'm365_service_health', which an agent could easily confuse with this server-side probe.

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

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

Usage is only implied: the probe's purpose (confirming Graph reachability, baseline permissions, optional licence/config availability) suggests calling it when diagnosing configuration or permission failures, but there is no explicit 'use this when' statement and no exclusion against m365_service_health or daily_brief.

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

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

With no annotations, the description carries the full burden and does so: it declares read-only semantics, the underlying call (GET /subscriptions), the RBAC prerequisite (nothing beyond visibility), the tenant boundary (DEFAULT tenant only even with multiple tenants configured), and the meaning of the `capped` signal when results are truncated. That is unusually rich behavioral disclosure.

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

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

The core statement and scope constraint come first, followed by a tight sequence of safety, routing, diagnostics, and the `capped` note — every element earns its place. The parenthetical ``ENTRAADM_CONFIG`` aside adds a bit of noise for an agent that cannot set env vars mid-call.

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

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

No annotations and no output schema, so the description must cover behavior and returns; it does cover read-only status, tenant scope, truncation, and the empty-result case. What it omits is the shape of a returned subscription (id vs display name fields), which matters because downstream tools accept either form.

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

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

Only one optional parameter exists and the schema documents none of it (0% coverage), so the description must compensate. It does partially by explaining the "page budget" concept behind `capped`, which an agent can connect to `max_pages`, but it never states what `max_pages` does, its default of null, or what value to pass to avoid truncation.

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

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

States a concrete verb/resource ("The Azure subscriptions this credential can see, as ARM lists them") and scopes it to the default tenant. No sibling in the list enumerates subscriptions, and the description explicitly names the two tools this result feeds, so an agent can place it precisely.

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

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

Explicitly frames the tool as "the discovery anchor for vm_backup_status and vm_backup_policies," telling the agent to call this first when those tools need a subscription id or display name. It also supplies interpretation guidance (an empty list with working auth means no Reader role was granted) and the tenant scope caveat, which is exactly the when/when-not context needed.

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

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

With no annotations, the description carries the full burden and does: two Graph reads, required ServiceHealth.Read.All permission, ordering (newest first), independent per-section degradation with an {"error","missing_permission"} shape, summary computed from partial results, and capped as a lower-bound flag. It even discloses that message center is deliberately not read.

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

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

Front-loaded with the one-line purpose, then progressively richer detail; every clause (degradation, capped semantics, excluded messages endpoint) adds needed context. Backtick-heavy prose makes it slightly denser than necessary but nothing is filler.

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

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

No output schema and no annotations, yet the description covers return structure (per-service rows, issues collection, summary, error sections), partial-failure semantics, and count caveats. An agent has everything it needs to call this and interpret the result.

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

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

Schema coverage is 0%, so the description must compensate, and it does for both parameters: max_pages as a per-collection page budget with its default constant, and tenant as a config section name or one of its domains. The default value referencing an opaque ENTRAADM_MAX_PAGES_DEFAULT symbol is the only minor gap.

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

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

The opening sentence names a specific resource (Microsoft 365 service status / open incidents and advisories) and a clear scope. It is unmistakable next to read-only log and audit siblings such as signin_logs or directory_audits, and it explicitly ties its role to daily_brief.

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

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

It gives a concrete decision context — a sign-in failure spike reads differently when Entra or Exchange has an open incident — which tells the agent when this matters. It does not state exclusions or an explicit 'use X instead of Y' routing, so it stops short of a 5.

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

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

No annotations exist, so the description carries the full burden and does: it declares read-only behavior, names the required permission (AuditLog.Read.All) and the azure-cli alternative (Reports Reader role), and explains capped/events_truncated semantics including that the users summary still counts truncated rows.

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

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

Well front-loaded and organized into prose plus an Args block, with no filler sentences. The return-shape paragraph is dense and slightly long, but each clause (users, events, capped, events_truncated) conveys distinct information.

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

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

There is no output schema, so the description must explain returns, and it does in detail: per-account summary with success/failure/first/last seen and the 50-account cap, newest top events with AADSTS annotation, plus the two truncation flags. Nothing an agent needs to call or interpret this correctly is missing.

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

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

Schema coverage is 0%, so the description must compensate, and it does — every parameter is documented with meaning, defaults, and clamping ranges (hours in [1,720], top in [1,500], result enum all/success/failure, tenant as config section or domain, max_pages budget).

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

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

Opens with a specific verb+resource+scope: every sign-in from one source IP, with who succeeded, who was tried, and when. It also distinguishes itself from adjacent tools (spray_suspects, shared_ips, signin_logs) that an agent might otherwise pick.

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

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

Explicitly frames itself as the follow-up to a spray_suspects or shared_ips hit and notes it is a single server-side filtered query, not a log walk — strong 'when to use' guidance. It does not explicitly say when to prefer the sibling signin_logs instead, leaving one routing decision to inference.

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

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

With no annotations, the description carries the full burden and does so: it discloses the read-only permission model (AuditLog.Read.All or Reports Reader), the ENTRAADM_DEADLINE cap and `capped=true` lower-bound semantics, the page-budget sampling behavior, and the fact that Graph cannot filter on status/errorCode server-side. Failure modes for the sites file (invalid CIDR still uses valid ranges, unreadable file demotes all IPs to `spray_suspects`) are also spelled out.

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

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

Purpose and the time-bound caveat are front-loaded, but the text is roughly 400 words for a three-parameter tool. The `capped=true` lower-bound/sample explanation appears twice, and the paragraph about RADIUS/KeyCloak parity and the official Microsoft MCP Server is vendor positioning rather than agent-relevant instruction.

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

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

There is no output schema, yet the description fully describes the returned views (`top_ips`, `spray_suspects`, `internal_spray_suspects`, `sites`/`sites.error`) and what the spray flag means. Combined with permissions, deadline behavior and degradation paths, an agent has everything needed to call and interpret it.

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

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

Schema coverage is 0%, so the description must compensate and does: `hours` is documented with its [1, 720] clamp, `max_pages` with its environment-variable default, and `tenant` with the accepted forms ([tenant.<name>] section or domain) and the default tenant fallback. Every parameter gains meaning not present in the bare schema.

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

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

Names a specific verb and resource — tenant-wide aggregation of failed sign-ins — and enumerates the four output views (AADSTS codes, failing users, apps, source IPs). Explicitly distinguishes itself from sibling `signin_logs` (which it references for error-code meanings) and from per-account/per-IP views, so an agent can route correctly without opening the schema.

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

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

Gives concrete operational guidance — narrow `hours` when the scan caps and you need a census rather than a sample, and the tool is positioned as the failure/spray counterpart to the success statistics and per-IP siblings. It lacks an explicit 'do not use this when…' exclusion (e.g. use `signin_logs` for individual event detail), which keeps it from a 5.

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

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

With no annotations, the description carries the full burden and does so: read-only, required AuditLog.Read.All permission (or Reports Reader role for azure-cli), the 30-day P1 retention limit and the fact that out-of-range `hours` returns empty rather than erroring. It also discloses the non-obvious client-side filtering/paging behavior and the precise meaning of `capped=true` so a low match count isn't misread as 'no failures exist'.

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

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

Front-loaded with the diagnostic payoff before any mechanics, and every paragraph adds information an agent needs. Minor redundancy: the client-side filtering rationale is restated twice ('filters client-side after the Graph fetch' then 'Because the filter is client-side'), costing a sentence.

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

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

No output schema exists, yet the description names the returned signals (`error_code_meaning`, `result`, `capped`) and explains each. Combined with permission requirements, retention limits and paging semantics, an agent has everything needed to call this correctly and interpret the response.

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

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

Schema description coverage is 0%, so the Args section is the only documentation and it covers all six parameters with real meaning: `user` is a UPN, `hours` clamps to [1,720], `result` has three values with client-side filter semantics, `top` clamps to [1,500], `max_pages` defaults to an env var, and `tenant` explains the onmicrosoft.com/#EXT#/B2B-guest cases. This substantially exceeds what the bare schema conveys.

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

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

States a specific verb+resource+scope: 'One user's recent sign-in events, AADSTS-annotated', and frames the diagnostic question it answers ('why can't this person log in'). The explicit 'One user's' scoping separates it from the aggregate siblings signin_failure_stats / signin_success_stats / signin_by_ip without needing to name them.

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

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

'The most direct answer to "why can't this person log in"' gives clear situational context for when to reach for this tool, and the result/top semantics imply the exploratory-vs-targeted use cases. It stops short of naming when NOT to use it (e.g. fleet-wide failure counts belong in signin_failure_stats), so no explicit exclusion.

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

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

With no annotations, the description carries the full behavioral burden and does so thoroughly: read-only access, required permissions, client-side aggregation, interactive-only sign-ins, capped results as lower bounds, and deadline/page-budget behavior are all disclosed.

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

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

The description is long but front-loaded and appropriately sized for a complex aggregation tool. Each paragraph adds operational meaning, and the Args section compensates for the schema's lack of descriptions rather than repeating structured data.

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

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

There is no output schema, but the description explains the returned views, caps, account limits, and caveats thoroughly enough for an agent to interpret results. It also covers permissions and aggregation limitations that are critical for correct use.

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

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

Although schema description coverage is 0%, the Args section fully explains each parameter: hours is clamped to [1, 720], max_pages uses an environment default, min_distinct_users defaults to 2 and is clamped to >= 2, and tenant accepts a tenant section name or domain.

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

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

The description states a specific verb and resource: tenant-wide successful sign-in aggregation by source IP. It explicitly distinguishes this tool from its sibling signin_failure_stats, making the intended view clear without opening either schema.

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

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

It names the alternative and the condition that selects it: signin_failure_stats shows who is attacked, while this tool shows whether anyone got in. It also warns that shared IPs from NAT, VDI, or proxies are leads rather than verdicts, which is explicit usage guidance.

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

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

With no annotations, the description carries the full burden and does so: states it is read-only, requires the Reader role, operates only in the DEFAULT tenant even when several are configured, and explains the dual-read strategy, page/time budgets, the 'capped'/'capped_reads' markers, and the critical caveat that an empty section is not proof nothing happened.

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

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

The headline answers are front-loaded and the bulleted breakdown of return sections is easy to scan. It is long and the tenant/search-completeness discussion is dense, but nearly every sentence adds operational value rather than repeating the schema.

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

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

No output schema exists, yet the description documents each returned section (health causes, vm_operations with caller and correlation_id, other_operations counts and truncation to 50, service_health, other_categories) plus the truncation flags. An agent has enough to call the tool and interpret results correctly.

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

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

At 0% schema coverage this description must compensate, and it largely does: explains vm name matching (case-insensitive, ambiguity via 'ambiguous'/'candidates'/'search_complete'), subscription and resource_group narrowing, the start/end/hours relationship with defaults, the 168-hour/90-day limits, and ISO offset format. The one gap is max_pages, which is never named or explained despite the repeated 'page budget' references.

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

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

Opens with a specific verb+resource+scope: 'What happened to an Azure VM in a time window: operations people ran, and events Azure raised.' It is clearly distinguishable from siblings like vm_backup_status or health_check, and the 'did someone restart this VM, or did Azure?' line pins the intent down further.

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

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

Gives a concrete scenario ('did someone restart this VM, or did Azure?') and tells the agent to use list_subscriptions to source the subscription identifier, plus when to add subscription/resource_group. It does not explicitly say when to prefer a sibling tool instead, which keeps it below a 5.

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

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

With no annotations, the description carries the full behavioral burden and does: it declares read-only, names the required Reader role, pins tenant scope, defines failure modes (unknown/ambiguous subscription → `found: false`), and guarantees no policy type is silently dropped (`{"type": <name>, "unparsed": true}`). It also explains the truncation model (skipped_vaults per subscription, skipped subscriptions on budget exhaustion, capped overall), which is exactly the kind of behavior an agent cannot infer elsewhere.

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

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

Front-loads purpose, then scope/permissions, then the per-field contract, then parameter and truncation semantics — a sensible reading order. It is dense and somewhat long, and the enumerated field glosses (V1/V2, retention blocks) are heavy, but each earns its place as the only documentation of the return shape given there is no output schema.

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

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

No output schema exists, so the description must define the return payload, and it does at the field level including the unparsed-type fallback and ARM's own protected_item_count. The only real gap is `max_pages`, whose paging behavior is gestured at ('budget', 'capped') rather than stated, which matters for an agent deciding how many calls to make.

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

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

Schema coverage is 0%, so the description must compensate, and it does for `subscription`: accepted forms, the None default's meaning, and the unknown/ambiguous resolution behavior. `max_pages` is never named directly — its effect is only inferable from the 'budget ran out' / `capped` language, leaving one of two parameters under-specified.

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

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

States the resource precisely (Azure VM backup policies per Recovery Services vault) and what it exposes (schedule and retention), and it implicitly distinguishes itself from the sibling vm_backup_status by deferring to it for coverage-flag semantics. It never uses an explicit retrieval verb, but 'Read-only' plus the per-policy field list makes the operation unambiguous.

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

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

Gives solid operating context: DEFAULT tenant only even with multiple tenants in ENTRAADM_CONFIG, read-only, Reader role on the subscription, and how to pass `subscription` (id or display name from list_subscriptions, None = all). What's missing is an explicit statement of when to reach for this tool versus vm_backup_status or vm_activity — the routing is only implied by the shared coverage-flag vocabulary.

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

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

With no annotations, the description carries the full disclosure burden and does so: read-only, requires the Reader role on the subscription, DEFAULT tenant even when multiple are configured, and a wall-clock budget that can leave subscriptions in 'skipped' with 'capped' set. It also documents failure semantics that would otherwise cause silent misinterpretation — a partial scan never yields a false 'unprotected', and a permission error on one subscription is reported per-entry while others still return.

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

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

The purpose is front-loaded in the first sentence and the remaining text is dense rather than padded — most of it is per-field return semantics that are necessary because no output schema exists. It is nonetheless long for a 3-parameter tool, with deeply nested parentheticals that slow scanning.

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

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

Given no annotations and no output schema, the description needs to explain both behavior and return shape, and it does: protected/backup_ok/stale semantics, duplicate_items and orphan handling, and partial-coverage signaling. The only meaningful omission is what max_pages controls and how it interacts with the 'capped' outcome.

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

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

Schema coverage is 0%, so the description must compensate. It fully specifies 'subscription' (id or display name from list_subscriptions; None scans all and joins globally) and 'stale_hours' (default 36h suits daily policies, raise for weekly ones, policy_name is in the row). 'max_pages' is left completely undefined, which is a real gap even though the wall-clock/capped behavior is described.

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

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

Opens with a specific verb+resource statement ('Which Azure VMs are backed up by Azure Backup, and whether the last backup succeeded') and immediately scopes it to the default tenant. This is clearly distinguishable from the sibling vm_backup_policies (which would concern policy definitions) without opening either schema.

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

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

Gives clear operating conditions: already-backed-up-by-Azure-Backup, DEFAULT tenant only, and points to list_subscriptions as the source of valid subscription values. It explains the None-vs-named-subscription semantics and the unknown/ambiguous-name behavior, but never states when an agent should prefer vm_backup_policies or vm_activity instead.

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