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

With no annotations, the description carries the full burden and largely meets it: it discloses that sections run synchronously in one call, that a permission failure degrades only that section's summary contribution while others still return in full, and that the page budget is shared across sections. It does not state permission scopes or explicitly declare the operation read-only, leaving a small gap.

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 before the correct usage routing and the arg list, and every paragraph addresses a decision the caller makes. It carries some low-value internal detail ('tracked in this repo's CLAUDE.md Roadmap') that an agent cannot act on, but the surrounding sentences about slowness and timeouts are genuinely actionable.

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 three-param, annotation-free read tool with no output schema, the description covers invocation, cost, failure modes, and exclusions thoroughly. The one residual gap is that the return shape is only characterized as a 'compact summary' matching other fleet daily_brief tools, so result structure must be discovered empirically.

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 does: hours is documented with its clamp range [1, 720] and meaning; max_pages is described as a budget passed to both sections with its default source; samples is flagged as reserved and currently unused, which directly prevents an agent from misusing it.

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 exactly what the tool returns: 'One-call morning-patrol summary: M365 service health, sign-in failures, spray suspects, admin actions.' It then names the three sibling tools it aggregates (m365_service_health, signin_failure_stats, directory_audits) and explicitly excludes vm_backup_status, so an agent can distinguish it from every sibling 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.

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

Gives explicit when-to-use (morning patrol, one-call aggregation), when-not-to-use-and-why (backup excluded because ARM fan-out would exhaust the shared budget; call vm_backup_status separately), and names the alternative implementation pattern (gwsadm-mcp job+poll) with the condition under which it would be preferred.

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 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.

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.

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.

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.

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.

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.

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

With no annotations, the description carries the full burden and excels. It discloses the meaning of key fields (account_enabled, on_premises_sync_enabled, licenses_capped), the graceful degradation of sign_in_activity without the required permission, and that a nonexistent account returns {'found': false} rather than an error. It also states the read-only nature and exact UPN requirement. 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.

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

Though long, the description is densely packed with prerequisite triage knowledge—field semantics, permission nuances, and edge cases—and every sentence adds value. It is structured with clear paragraphs and code-formatting for fields, making it scannable. The front-loaded purpose statement ensures the agent quickly knows what the tool does.

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 tool with no output schema, the description covers the essential return fields (account_enabled, last_password_change_date_time, on_premises_sync_enabled, licenses, licenses_capped, sign_in_activity), their meanings, and expected edge behavior. It also describes permission requirements and the graceful degradation path. Nothing an agent needs to call it and interpret results 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 for the only parameter, upn, is 0%, but the description fully compensates: 'Args: upn: The account's userPrincipalName, e.g. "user@example.edu".' It also stresses the need for an exact match, not display name. This gives the agent everything needed to format the argument correctly.

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 opens with 'One account's identity/lifecycle state -- the first thing to check on any triage report.' This is a specific verb+resource (get identity/lifecycle state) and explicitly positions it as the initial step, distinguishing it from sibling tools that focus on sign-in logs, auth methods, or audits. The purpose is unmistakable and actionable.

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 clear context: 'first thing to check' and instructs to 'stop there' if account_enabled=false. It also explains a common pattern for stale passwords. However, it never explicitly names alternative tools or states when not to use this tool (e.g., 'for auth methods, use get_user_auth_methods'). The order is implied but not contrasted with siblings.

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 provided, the description carries the full burden of behavioral disclosure. It explicitly states the read-only permission, the app-only limitation that leads to permission errors under azure-cli, the behavior for nonexistent accounts (returns a specific structure instead of an error), and the precise semantics of mfa_registered. It does not detail the full response structure for existing accounts, which is a minor gap, but the key behaviors are well covered.

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 well-structured with a clear opening statement, a code-formatted explanation of the key field, a note on nonexistent accounts, and a security/permission caveat. It is informative but not bloated; each paragraph serves a distinct purpose. It could be slightly more concise, but the structure aids readability.

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?

The description fully covers the MFA-checking purpose and the nonexistent-account case, but it does not specify the full response format for an existing account beyond the mfa_registered boolean. Since there is no output schema, an agent may not know if the response includes a list of methods, their types, or other fields. This is a notable gap for a tool that returns a data structure, though it may be sufficient for the primary use case of checking MFA.

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?

The schema provides only the parameter name 'upn' with no description (0% coverage). The description compensates by stating 'Args: upn: The account's userPrincipalName.' This adds the meaning and domain context, making it clear what value to provide. While it doesn't elaborate on format or constraints, the parameter is simple and the explanation is sufficient.

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 opens with a clear, specific purpose: retrieving registered authentication methods for an account and determining whether MFA is actually set up. It explains the key field (mfa_registered) and distinguishes itself from sibling tools that deal with sign-in logs or audits. The verb and resource are unambiguous, and the contrast with other tools is implicit but effective.

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 provides clear context on when to use this tool (to check MFA coverage) and includes a practical caveat about app-only auth under azure-cli. It references get_user's contract for nonexistent accounts, offering a form of alternative comparison. However, it does not explicitly name siblings like signin_logs or signin_failure_stats as alternatives, leaving some usage inference to the agent.

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, enumerates the probes and required permissions, states both probes always run independently, defines the healthy/degraded/error derivation, guarantees a stable key set with detail null on success, and explains the ARM probe's isolation and timeout budget. This is unusually complete 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 is well front-loaded, but the definition runs five dense paragraphs for a zero-argument probe. Passages about `_ARM_PROBE_SECONDS`, azure-identity's synchronous token acquisition, and azure-cli shelling out are implementation trivia that do not help an agent select or invoke the tool, so not every sentence earns its place.

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 (and does) explain the return shape: the service/version/status keys, the sites and arm sub-objects, the three status values, and the guarantee that detail is null on success. Nothing an agent needs to call and interpret this tool 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?

The tool takes zero parameters, so the baseline of 4 applies; there are no arguments whose meaning needs supplementing. The description instead spends its effort on return-key semantics, which belongs to contextual completeness rather than parameter semantics.

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: 'Fleet-standard health probe: service/version/status plus two independent Graph probes.' It is unmistakably about this server's own readiness, which separates it from the sibling m365_service_health (tenant service status) and from the data tools it gates. An agent knows what this returns without opening anything else.

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 provides strong interpretative context — what each probe proves about permissions, and why a missing baseline permission would fabricate a 'Graph unreachable' diagnosis — which implicitly tells the agent when this tool is the right diagnostic. However, it never states when to call it versus m365_service_health or daily_brief, and offers no explicit exclusions, 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?

With no annotations provided, the description carries the full behavioral burden and does so: it declares the operation read-only, states the RBAC requirement (no role beyond being able to see a subscription), explains what an empty result implies, and defines the `capped` truncation flag. This is exactly the beyond-schema context annotations would otherwise supply.

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 one clean sentence, followed by progressively finer behavioral detail in short blocks. The parenthetical ARM/RBAC aside and backtick formatting add usable precision, though the phrasing is slightly literary ('as ARM lists them') for an agent-facing description.

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 no-annotation, single-parameter, no-output-schema tool this covers the essentials: read-only nature, auth/RBAC expectations, empty-result meaning, and truncation signal. It stops short of describing the returned item shape beyond noting id and display name are usable as inputs.

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% and the single `max_pages` parameter is entirely undocumented in the schema. The description alludes to a 'page budget' and a `capped` truncation flag, which lets an agent infer that paging is bounded, but it never names the parameter, its default (null), or what value would 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?

The first sentence names the exact resource (Azure subscriptions), the scope (those this credential can see), and the underlying operation (`GET /subscriptions`, i.e. an ARM list). It further distinguishes itself from siblings by identifying itself as the discovery anchor for `vm_backup_status` and `vm_backup_policies`, so an agent can place it without opening any 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?

Explicitly states the when-to-use path: this is the source of subscription ids or display names that the two backup sibling tools accept. It also gives a diagnostic trigger — an empty list while `auth` works means no Reader role has been granted anywhere. Both an entry point and an alternative-selection rule are present.

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 names the required Graph permission, discloses per-section degradation with a concrete error shape ({"error", "missing_permission"}), explains that summary is derived from whatever returned, defines 'capped' as lower-bound counts due to the page budget, and notes the message center is out of scope.

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 is front-loaded in the first sentence, with operational detail following. The heavy use of backticked fragments and parentheticals makes it dense, but nearly every clause adds information rather than restating structured 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?

For a read tool with no annotations and no output schema, it adequately describes the return shape (one row per service, unresolved issues newest-first) and failure modes. It could go further on how degraded sections appear alongside computed summaries, but the essentials are present.

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% for the single max_pages parameter, so the description must compensate. It introduces the 'page budget' concept and the 'capped' consequence, which implies what max_pages controls, but it never names or defines the parameter's units or 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?

States a specific resource and scope: M365 service status per service plus open incidents and advisories, and names the two Graph collections it reads (healthOverviews and serviceAnnouncement/issues). It also draws a boundary against a sibling (daily_brief carries this section) and against the message center, which it explicitly does not read.

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?

Provides clear diagnostic context for when this matters ('a sign-in failure spike reads very differently while Entra or Exchange has an open incident') and links to the daily_brief consumer. It stops short of explicit when-to-use/when-not-to-use routing against the other sibling tools, so no full 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 thoroughly: it declares read-only status, states the exact permission/role required (AuditLog.Read.All application permission or Reports Reader role), and explains operational signals (capped, events_truncated) beyond anything in structured fields.

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 behavior before the Args block. The prose is dense and slightly wordy in places (e.g., the elaborated users/events description), but each sentence conveys usable information rather than 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?

With no annotations and no output schema, the description still explains return structure (users summary with up to 50 accounts, events with AADSTS annotations, capped/events_truncated flags), permissions, and all parameter semantics. Nothing an agent needs to invoke 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 description coverage is 0%, so the description must compensate, and it documents all five parameters: ip format, hours clamp [1,720], result enum values, top clamp [1,500], and max_pages default. This is exactly the compensation required when the schema is silent.

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 a specific verb+resource+scope: 'Every sign-in from one source IP: who got in from it, who was tried, and when.' It also implicitly separates itself from signin_logs by framing the results as IP-scoped, and names upstream triggers (spray_suspects, shared_ips).

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?

Clearly positions itself as 'the follow-up to a spray_suspects or shared_ips hit' and explains that Graph filters on ipAddress server-side, making it a cheap query rather than a log walk. It does not explicitly name signin_logs as the alternative to use for non-IP-scoped queries, so the when-not is only implied.

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 zero annotations, the description carries the full behavioral burden and does so thoroughly: read-only status, required AuditLog.Read.All permission or Reports Reader role, the ENTRAADM_DEADLINE time budget, the meaning of capped=true, client-side aggregation due to Graph's lack of server-side status filtering, and site/CIDR error 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 purpose and time-bound caveat are front-loaded, and most detail is load-bearing for a tool with no annotations. Some sentences stray into marketing/backstory (the KeyCloak fleet comparison and 'neither the official Microsoft MCP Server... nor Graph itself offers this'), which could be trimmed without loss.

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 fully specifies the returned views, the capped/lower-bound semantics, permission requirements, and site-file failure modes. An agent has everything needed to call and interpret the tool.

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: 'hours' is documented with its [1, 720] clamp and 'max_pages' with its ENTRAADM_MAX_PAGES_DEFAULT default and its role in triggering capped counts. This adds meaning the bare schema (titles and defaults only) does not provide.

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 and resource ('Tenant-wide sign-in failure aggregation') and enumerates the four output views (AADSTS error codes, failing users, applications, source IPs). It clearly distinguishes itself from siblings by naming its counterpart ('RADIUS failure patrol') and contrasting with per-account views like signin_logs and signin_by_ip.

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 usage context: narrow 'hours' for a full count, capped counts are a lower bound, and it is the aggregation a per-account view cannot produce. However, it never explicitly routes the agent between signin_failure_stats, signin_logs, and signin_success_stats, leaving that inference to the reader.

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 provided, the description carries the full burden and excels. It discloses read-only permissions (AuditLog.Read.All or Reports Reader), retention limits (30 days), clamping behavior, client-side filtering, page-walking mechanics, and the meaning of capped=true. It even clarifies that low match counts with capped=true indicate a budget limit, not absence of data. This is a model of transparency.

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 well-structured, front-loading the core purpose, then providing necessary nuance about filtering and paging, then permissions, then a clean parameter list. Every sentence contributes to correct usage; there is no filler or redundancy. It is long but appropriately so for a tool with complex client-side behavior.

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 the complexity (client-side filtering, pagination, permission requirements, retention window, edge cases) and the absence of an output schema, the description is remarkably complete. It covers all scenarios an agent needs to invoke the tool correctly and interpret results, including the capped flag and empty results. Nothing critical 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%, but the description compensates thoroughly. It explains each parameter in detail: user's userPrincipalName, hours clamped to [1,720], result options with default 'failure', top clamped to [1,500], and max_pages with default. It also explains the functional meaning of result (client-side filter) and the cap semantics, providing far more than 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?

The description explicitly states the tool returns 'one user's recent sign-in events' and frames it as 'the most direct answer to why can't this person log in'. It identifies the AADSTS annotation as a key value-add, distinguishing it from sibling tools like signin_failure_stats that likely provide aggregated statistics. The purpose is specific and immediately actionable.

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 gives explicit usage context: it is positioned as the go-to for individual login troubleshooting, and it explains important behavioral caveats like client-side filtering that require adjusting expectations. It implies when not to use it (e.g., for stats, use signin_failure_stats) and details what happens when the page budget is exhausted (capped=true). Alternatives are not explicitly named but clearly indicated by 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, the description carries the full behavioral burden and does so: read-only, required permission (AuditLog.Read.All / Reports Reader role), client-side aggregation because Graph cannot filter on status/errorCode server-side, interactive-sign-ins-only scope with the reasoning that legacy auth is logged as interactive, and lower-bound semantics when the page budget or ENTRAADM_DEADLINE expires. This is exactly the context annotations would otherwise supply.

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 failure/success contrast are front-loaded, and the dense middle does real work. It is longer than strictly necessary — the breach-signature narrative and the NAT/VDI caveat could be tightened — but almost every sentence carries operational information rather than padding.

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 explain return values directly, and it does: shared_ips (up to 50, ordering, per-IP account/client-app/country detail, shared_ips_capped) and legacy_auth_users with IP/country counts. Combined with the permission, scope, and cap caveats, an agent has everything needed to call and interpret this tool.

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 clamped to [1,720], max_pages defaulting to ENTRAADM_MAX_PAGES_DEFAULT (page budget), and min_distinct_users defaulting to 2 with a clamp of >=2. No parameter is left to inference.

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 precise verb+resource+scope (tenant-wide successful sign-in aggregation by source IP) and explicitly contrasts itself with the sibling signin_failure_stats ('shows who is being attacked; this shows whether anyone got in'). An agent can distinguish it from every sibling 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.

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

Explicit routing to signin_failure_stats, plus genuine interpretation guidance: shared IPs are 'a lead, not a verdict' because NAT/VDI/proxy produce the same signature, and it tells the caller to exclude its own egress ranges before concluding a breach. It also names the condition that invalidates results (capped=true) and the remedy (narrow hours).

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, the Reader role prerequisite, the unknown-type fallback ({"type": <name>, "unparsed": true}, never dropped), the found: false behavior for unknown/ambiguous subscription names, and the skipped/capped coverage semantics. It stops short of describing pagination behavior or result volume.

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 safety profile are front-loaded in the first two lines, and the remaining dense blocks each document a distinct behavior (output shape, fallback, parameter semantics, coverage flags) with no filler or repetition.

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 describe returns, and it does so thoroughly: per-policy fields, the unparsed fallback, and the coverage flags. The only real gap is the unexplained max_pages control, which matters for a paginated multi-subscription read.

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 explains subscription (id or display name from list_subscriptions, None = all, ambiguous name yields found: false), but max_pages is never mentioned except obliquely through the 'budget ran out' coverage flag, leaving one of two parameters undocumented.

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 names the specific resource (Azure VM backup policies in each Recovery Services vault) and the exact payload (schedule and retention), so an agent knows precisely what it retrieves. It lacks an explicit verb (List/Get) and its differentiation from siblings is only implicit via a reference to vm_backup_status.

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 states the read-only nature and the required Reader role, and clarifies that subscription comes from list_subscriptions with None meaning all visible subscriptions. However, it never explicitly says when to prefer this tool over vm_backup_status or the other backup/log siblings, leaving routing 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 richly: read-only, requires the Reader role on the subscription, explains that a partial scan never yields a false 'unprotected', how duplicate vault items are resolved, how orphans are only reported on fully-listed subscriptions, and how permission errors and the wall-clock budget (capped/skipped) surface.

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 one-line summary followed by scannable bullet groups for each per-VM field. It is long, but for a join with this much conditional output semantics, nearly every sentence adds needed precision, so only minor trimming is possible.

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, yet the description effectively documents the return contract (protected, backup_ok, stale, orphans, skipped, capped, found). For a complex cross-service join with no annotations, an agent has everything needed to call and interpret it 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?

Schema coverage is 0%, so the description must compensate. It thoroughly explains subscription (id or display name, None scans all) and stale_hours (default 36 for daily policies, raise for weekly). max_pages is only obliquely implied through the capped/skipped discussion and is never named, leaving one of three 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?

The opening line gives a specific verb and resource ('Which Azure VMs are backed up by Azure Backup, and whether the last backup succeeded') and the body names the exact Azure resource types it joins. It is plainly distinguishable from the sibling vm_backup_policies, which handles policies rather than per-VM status.

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 useful usage context – pass a subscription id/name from list_subscriptions, pass None to scan everything, raise stale_hours from 36 for weekly policies. However, it never explicitly states when to choose this over vm_backup_policies or the other siblings, leaving the routing to inference.

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