Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@defender-xdr Show me the latest high-severity incidents from the last 24 hours."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Model Context Protocol (MCP) servers, and the typed tool clients they wrap, for security operations.
MCP servers are the integration layer that lets AI agents query security platforms directly — the source of truth — instead of copying telemetry into yet another data lake. This repository is the ZeroSOC Framework community's home for MCP servers covering major security technologies that lack an official or complete one.
For each security technology we pick exactly one engagement mode:
Mode | When | What we do |
Adopt | An official vendor (or healthy third-party) MCP server exists and is adequate | Reference it via its package manager distribution. We never fork-and-diverge. |
Contribute | A server exists but is partial | Contribute enhancements upstream, under the upstream project's license and governance. |
Build | No usable server exists | Build and maintain it here — vendor-neutral, permissively licensed, production-quality. |
Sunset policy: when a vendor ships an official server for a technology we Build, we converge — we contribute our learnings and tests upstream, put our server in maintenance mode with a migration note, and offer to donate the codebase to the vendor. The goal is ecosystem health, not ownership.
Related MCP server: Microsoft Graph MCP Server
Technology | Mode | Status | Server / upstream |
Microsoft Defender XDR | Build | Active | |
Google SecOps (Chronicle) | Contribute | Planned | Official server exists but is partial; upstream contributions being scoped |
CrowdStrike Falcon | Adopt | Evaluating | Official/third-party options under evaluation |
Microsoft Sentinel | — | Candidate | Not yet scoped |
Want a technology covered? Open an issue with the vendor, the API surface, and links to any existing MCP servers.
Every integration built here ships as a tool client (clients/<technology>/, a typed Python library) and an MCP server (servers/<technology>/) that is a thin wrapper over it. Agents use the server from any MCP host; programs call the client directly where the path must be deterministic. Each API call is implemented once, so both see the same behaviour. Each server also ships a capabilities manifest and, where the technology allows it, a capability probe that writes a ZeroSOC capability binding file for what a given tenant exposes.
Servers run standalone. The server and its tool client are two packages in this repository, so both are named on the command line:
uvx --from "git+https://github.com/ZeroSOC/zerosoc-mcp@<tag>#subdirectory=servers/<technology>" \
--with "git+https://github.com/ZeroSOC/zerosoc-mcp@<tag>#subdirectory=clients/<technology>" \
<command>Every server built here meets the same bar:
Safe by default — read tools and response/write tools are separated; destructive response actions are disabled unless explicitly enabled per deployment via an environment flag.
Context-friendly — every list tool paginates with sane caps; no unbounded dumps into an agent's context window.
Actionable errors — API failures surface the status and a remediation hint (e.g. the exact missing permission).
No secrets — configuration via environment variables only, documented in each server's .env.example; required API permissions are documented per tool group.
servers/defender-xdr — Microsoft Defender XDRIncidents with their full evidence inventory, alerts, cross-workload advanced hunting and Entra ID logs via Microsoft Graph, a capability probe, plus device response actions, threat indicators, and vulnerability management via the Microsoft Defender for Endpoint API. See its README for setup, and clients/defender-xdr for the tool client.
See CONTRIBUTING.md. Contributions are accepted under Apache 2.0 with DCO sign-off (git commit -s); there is no CLA. Taking part means keeping to the Code of Conduct.
Please do not put real tenant data in an issue or a pull request — no device or user names, tenant identifiers, hashes or incident exports.
Found a vulnerability? Do not open a public issue. See SECURITY.md for private reporting and what is in scope.
Apache 2.0. Portions derived from MIT-licensed prior work — see NOTICE.
Append a comment to an alert's comment thread (a triage write), visible to analysts in the Defender portal. Notes about the whole case belong on the incident instead.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | Yes | The comment text to append to the thread. | |
| alert_id | Yes | The alert ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds useful behavioral detail beyond annotations: it specifies that the operation is an append (not an overwrite), that the comment becomes visible to analysts in the Defender portal, and frames it as a triage write. Annotations already signal readOnlyHint=false and destructiveHint=false, and the description does not contradict them.
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?
Two sentences deliver the action, the resource, the context, and routing advice with no wasted words. The primary purpose is front-loaded, and the second sentence earns its place by steering the agent away from the wrong sibling tool.
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 simple two-parameter mutation tool with full schema coverage and no output schema, the description is complete: it explains what happens, who sees the result, and how to differentiate it from the incident-comment tool. Nothing essential 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 100%: both alert_id and comment have clear descriptions in the schema. The tool description does not add any parameter-specific detail beyond what the schema already provides, so it meets the baseline without exceeding 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?
The description states a specific verb ('Append a comment'), a clear resource ('an alert's comment thread'), and the purpose ('a triage write'). It also distinguishes itself from the incident-comment sibling by explicitly noting that whole-case notes belong on the incident, so an agent can select this tool without ambiguity.
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 clear context for when this tool is appropriate: appending a comment to an alert thread. It also provides an exclusion and alternative by stating that case-level notes belong on the incident instead, which implies the sibling defender_add_incident_comment. It could be more explicit about when not to use it, but the guidance is strong enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Append a comment to an incident's comment thread (a triage write), visible to analysts in the Defender portal. If the incident was merged into another, the comment is written on the master incident, where analysts will read it, and redirectedFrom says so.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | Yes | The comment text to append to the thread. | |
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal a non-read, non-destructive operation, but the description adds critical behavioral detail: comments on merged incidents are written to the master incident and a redirectedFrom field communicates this redirection. This is the kind of hidden behavior an agent cannot infer from schema or annotations, and it directly affects where output will appear.
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?
Two sentences, zero filler. The core action is front-loaded, and the important edge case about merged incidents is introduced with a conditional ('If the incident was merged...') that leads naturally to the redirectedFrom outcome. Every clause 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?
Given the tool's simplicity (two required string params, no output schema), the description sufficiently covers the action, the audience (analysts), and the only notable behavioral twist (merged incidents). A minor omission is the lack of mention of what the tool returns, but this is a low-complexity write operation where return value is rarely critical.
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 100%, with both incident_id and comment already documented. The description repeats the word 'comment' but adds no new parameter-level meaning beyond what the schema provides. Baseline 3 applies because the schema carries the full burden.
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 specific verb and resource: 'Append a comment to an incident's comment thread,' which is unambiguous and differentiates from sibling tools like defender_add_alert_comment (which targets alerts, not incidents). The phrase 'a triage write' further clarifies the operational role, and the merged-incident behavior adds specificity without obscuring the core purpose.
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 implies appropriate use ('triage write,' 'visible to analysts') but does not explicitly state when to choose this tool over alternatives like defender_update_incident or defender_add_alert_comment. There is no mention of exclusions or conditions that would route an agent elsewhere, so context is present but left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a tag to a device or remove one (a metadata write).
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | Tag value. | |
| action | Yes | Add or Remove. | |
| machine_id | Yes | The Defender for Endpoint machine (device) ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false and destructiveHint=false. The description adds the useful qualifier that the operation is 'a metadata write,' clarifying the scope of side effects beyond what annotations state. It does not cover edge cases like duplicate tags or removing a nonexistent tag, but the core behavior is transparent.
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 a single front-loaded sentence with no filler. The parenthetical 'a metadata write' adds meaningful behavioral context without bloating the 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 simple three-parameter mutation with a complete schema and informative annotations, this is mostly complete. It lacks return-behavior or edge-case details, but those are minor given the tool's low complexity and absence of an output schema.
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 100%, so machine_id, value, and action are already fully documented in the structured schema. The description repeats the tag/device relationship but adds no additional parameter-level semantics such as format, constraints, or 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 uses a specific verb phrase, 'Add a tag to a device or remove one,' names the resource ('device'), and captures the dual action semantics from the enum. This clearly distinguishes it from the many read-only get_/list_ siblings.
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?
No guidance is given about when to use this tool versus alternatives such as defender_update_machine or defender_find_machines_by_tag. The intended usage is only inferable from the action enum and the sibling context, not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Decode a PowerShell -EncodedCommand payload (base64 of UTF-16LE) exactly. Accepts the full
command line, any spelling of the flag (-e, -enc, -ec, ...), or the bare base64. Use it
instead of decoding by hand. A decoding that is itself an encoded command is decoded again,
up to five rounds: rounds is how many layers were removed and capped says the command was
still encoded when they ran out. The evidence inventory already carries decoded_command,
decode_rounds and decode_capped on process rows.
| Name | Required | Description | Default |
|---|---|---|---|
| command_line | Yes | A command line containing -EncodedCommand, or the bare payload. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable behavioral context: it discloses the recursive decoding behavior (up to five rounds), the meaning of the `rounds` and `capped` outputs, and the fact that the evidence inventory already carries decoded fields. This goes beyond what annotations provide, though it doesn't describe error cases or exact output structure.
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 compact and front-loaded: it states the core action and format first, then input flexibility, then behavioral details. Every sentence earns its place, and there is no redundant or filler content.
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 single-parameter, read-only decoding tool with full schema coverage, the description is nearly complete. It explains the recursive decoding behavior, the output fields (`rounds`, `capped`), and the relationship to the evidence inventory. It doesn't describe the exact return value structure, but there is no output schema and the description gives enough for an agent to understand what will happen.
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 100%, so the schema already documents the single parameter. The description adds context about accepted input forms (full command line, any flag spelling, bare base64), which is useful, but it doesn't add much beyond what the schema's description already implies. Baseline 3 is appropriate because the schema does the heavy lifting.
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 ('Decode'), a precise resource ('PowerShell -EncodedCommand payload'), and the exact format (base64 of UTF-16LE). It also distinguishes itself from sibling tools by focusing on decoding rather than retrieval or management operations, so an agent can clearly identify when this tool is relevant.
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 explicitly says 'Use it instead of decoding by hand,' which gives a clear when-to-use directive. It also explains the accepted input forms (full command line, any flag spelling, bare base64), which is practical usage guidance. It doesn't explicitly name an alternative tool, but the sibling list shows no other decoding tool, so the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the short-lived download links of the full antivirus health report of every device. For a bounded look at it use defender_get_device_health.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only. The description adds behavioral context by noting the links are 'short-lived' and that the report is a full export of every device, which implies a potentially large result. This enriches the annotation without contradiction.
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?
Two sentences, no fluff. The main purpose is front-loaded and the sibling alternative is appended in a compact second sentence, so every word 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?
For a zero-parameter, read-only, export tool, the description is nearly complete. It tells an agent what the output is (download links), their temporary nature, and the scope. It doesn't specify report format, but this is a minor omission given no output schema or params.
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 has zero parameters, so the schema fully describes the input. With no params to document, the description only needs to avoid implying any filter; it clarifies the all-devices scope, meeting the baseline for no-parameter tools.
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?
Description explicitly states the verb 'Get' and the resource: 'short-lived download links of the full antivirus health report of every device.' It also contrasts with the bounded sibling defender_get_device_health, making the purpose 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?
The second sentence provides an explicit alternative: 'For a bounded look at it use defender_get_device_health.' This tells the agent exactly when to choose this tool over the sibling, fulfilling the usage guidance dimension.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a per-device assessment: one row per device and software, vulnerability, configuration or browser extension. The full export is large; this returns one bounded page and the next link.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of rows to return (default 50, max 500). | |
| assessment_type | Yes | Which per-device assessment to read. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool readOnly and non-destructive, so the safety profile is covered. The description adds a valuable behavioral trait beyond annotations: the export is large, results come in bounded pages, and a next link is provided.
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?
Two sentences carry all the essential information with no filler. The first sentence gives the verb and resource; the second explains scale and pagination, making it appropriately-sized and front-loaded.
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 simple two-parameter tool with no output schema and readOnly annotations, the description covers purpose, row granularity, scale, and pagination. The return shape beyond 'bounded page' is left unspecified, but the next-link mention gives an agent enough to proceed 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?
The schema already gives full coverage for both parameters, including enum meanings and top's default/max, so the baseline is 3. The description adds row-granularity semantics ('one row per device and software...') that clarify what assessment_type actually represents, justifying a 4.
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 begins with a specific verb-resource pair ('Read a per-device assessment') and enumerates the four assessment types, making the core purpose clear and matching the schema enum. It does not explicitly name a sibling tool to differenciate from, so it stops short of the strongest sibling differenciation.
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 useful context by noting that the full export is large and that this tool returns one bounded page plus a next link, implying use for paginated bulk reads. It does not state when to prefer this over the many sibling get_* tools, nor does it give any exclusions or alternative routes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the devices that had an IP address around a given time.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IP address to search for. | |
| top | No | Maximum number of machines to return (default 25, max 200). | |
| timestamp | Yes | UTC ISO 8601 time; devices seen with the IP within 15 minutes. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already cover the safety profile: readOnlyHint=true, destructiveHint=false, and openWorldHint=true. The description adds a temporal/historical framing but does not disclose the 15-minute window, result limits, pagination, or other runtime behavior; the schema partially covers those details.
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 one short, front-loaded sentence that states the tool's purpose without filler or redundancy. It is concise and easy to parse.
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 simple read-only lookup tool, the description plus fully described parameters and safety annotations are mostly sufficient. It does not describe the return shape, but no output schema exists and 'Find the devices' reasonably implies a list 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 description coverage is 100%, with ip, top, and timestamp all described. The description adds no parameter-level detail beyond mentioning 'IP address' and 'given time', so the baseline 3 is appropriate.
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 uses a specific verb ('Find') and resource ('devices that had an IP address around a given time'), and the IP-plus-time scope clearly distinguishes it from sibling tools like defender_get_machines, defender_get_ip_alerts, and defender_find_machines_by_tag. The core function is 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?
The intended use case—historical device lookup by IP at a given time—is implied but not explicitly stated. There is no mention of when to prefer this tool over alternatives such as defender_find_machines_by_tag or defender_get_ip_alerts, nor any exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find the devices that carry a tag.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | Yes | Machine tag to search for. | |
| top | No | Maximum number of machines to return (default 25, max 200). | |
| starts_with | No | Match tags that start with the value instead of equal it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds no additional behavioral context—such as return format, pagination behavior, or potential empty results—beyond what annotations and the schema provide. It does not contradict annotations, but it also does not enrich them.
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 a single, concise sentence that front-loads the core purpose. It is appropriately sized with no redundant words, though it might be slightly too terse to include helpful context like parameter usage. It earns its place as a clear and efficient statement.
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 three parameters, no output schema, and many sibling tools, the description is insufficient. It does not explain what the response will look like, how to leverage top and starts_with, or when to choose this tool over alternatives. The agent would need to rely on the schema and external knowledge to use 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 description coverage is 100%, so all parameters (tag, top, starts_with) are already documented with clear descriptions. The tool description does not add any extra meaning or context for these parameters; it only restates the core action. Since the schema carries the full burden, the baseline of 3 is appropriate.
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 'Find the devices that carry a tag' clearly states the verb (find) and resource (devices) with a specific condition (carry a tag). It is distinct from siblings like defender_find_machines_by_ip and defender_get_machines, though it does not explicitly name alternatives. The purpose is unambiguous and directly tied to the tool name.
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 implies usage for searching machines by tag, but it does not provide explicit guidance on when to prefer this tool over alternatives such as defender_get_machines or defender_find_machines_by_ip. There are no stated exclusions or references to sibling tools, so the agent must infer usage from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one alert with its full evidence (files, processes, registry keys, IPs, URLs, users, mailboxes, devices), MITRE techniques, detection source, detector ID and comment thread.
| Name | Required | Description | Default |
|---|---|---|---|
| alert_id | Yes | The alert ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description adds meaningful behavioral context: the tool returns evidence categories, MITRE techniques, detection source, detector ID, and the comment thread. This goes beyond what the annotations convey without contradicting them.
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 a single well-structured sentence that front-loads the operation and then lists concrete returned entities. Every phrase adds value and there is no repetition or 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?
For a single-parameter read-only tool, the description is reasonably complete: it specifies what is returned in detail, and the schema covers the required input. The absence of an output schema is mitigated by the explicit list of included fields, though error/not-found behavior is not mentioned.
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 input schema fully documents the single parameter alert_id with 'The alert ID.', giving 100% schema coverage. The description does not add further parameter syntax or constraints, so the baseline of 3 is appropriate.
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 a specific verb ('Get'), a specific resource ('one alert'), and enumerates the returned content ('full evidence', 'MITRE techniques', 'detection source', 'detector ID', 'comment thread'). This clearly differentiates it from sibling tools like defender_list_alerts or defender_get_incident.
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 implies use for retrieving a single alert's full details, but it does not explicitly state when to prefer this over alternatives such as defender_list_alerts or defender_update_alert. The 'one alert' wording gives context, but there are no explicit exclusions or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
What this tenant exposes, as a ZeroSOC capability binding. Call it once before
investigating. It checks which hunting tables hold data, which are exposed but empty and
which the licence does not expose at all, which APIs answer, and which application
permissions are granted, so an empty query result is read correctly: a visibility gap, a
missing licence or a missing permission. Returns capabilities (capability class to tool),
data_sources (each playbook data source, available or not, with the reason in
data_source_notes) and probe (every check, the granted roles, the classes left unbound
and the checks that stay manual). The probe only reads; the result is kept until refresh.
| Name | Required | Description | Default |
|---|---|---|---|
| refresh | No | Probe the tenant again instead of returning the last result. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false; the description reinforces and extends this by stating 'The probe only reads; the result is kept until refresh.' It also discloses caching/refresh behavior and the categories of checks performed, which adds genuine behavioral context beyond the 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?
The description is dense but every sentence earns its place: purpose, usage timing, interpretation semantics, return fields, and refresh behavior are all covered. The key directive 'Call it once before investigating' is front-loaded. Slightly long-winded in the middle, but nothing is redundant.
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 output schema, the description carries the burden of explaining return values, and it does: `capabilities`, `data_sources`, and `probe` are each described with their meaning. It also explains the real-world interpretation of empty results, which is critical context for an agent deciding whether a downstream query returned nothing due to a real gap.
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 100%, so the baseline is 3. The description adds value by explaining the 'result kept until refresh' caching mechanism, which clarifies what the `refresh` boolean does in practice. This contextualizes the parameter beyond the schema's 'Probe the tenant again instead of returning the last result.'
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 clear verb+resource: it probes what the tenant exposes as a capability binding, checking hunting tables, APIs, and permissions. It is distinctly a visibility/meta tool among siblings that fetch specific entities (machines, vulnerabilities, software). It never names a sibling explicitly, but the 'call it once before investigating' framing makes its unique role unmistakable.
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 concrete usage direction: 'Call it once before investigating.' It also explains the decision-relevant outcome—interpreting empty query results as visibility gap, missing licence, or missing permission. It does not list exclusions or explicit alternatives, but the 'call before investigating' directive is sufficient for a tool with no close sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the antivirus health of devices: mode, engine, platform and signature versions and their freshness, last quick and full scan. A device whose antivirus is passive, disabled or out of date explains a missing detection.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of devices to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety. The description adds behavioral value beyond annotations by specifying the exact health dimensions returned and how to interpret them (missing detections tied to antivirus state). No contradictions with 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?
The description uses two compact sentences with zero filler. The primary action and return fields are front-loaded, and the diagnostic note is placed second, making the purpose immediately clear.
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 output schema, the description carries the burden of explaining return values, and it does so by listing mode, engine, platform, signature versions, freshness, and last scans. Both parameters are fully documented in the schema, and the diagnostic context completes the picture. Nothing essential for invoking this simple list tool 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 100%, so the schema already documents 'top' and 'filter' with defaults, max, and filter guidance. The tool description does not add further parameter-level meaning, so a baseline 3 is appropriate.
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 uses a specific verb ('List') and resource ('antivirus health of devices') and enumerates the exact attributes returned (mode, engine, platform, signature versions, freshness, scans). This clearly distinguishes it from sibling tools like defender_get_secure_score or defender_get_machines_by_vulnerability, and even from the export-focused defender_export_antivirus_health.
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 second sentence provides clear diagnostic context: a device with passive, disabled, or outdated antivirus explains a missing detection. This effectively tells the agent when this tool is relevant. However, it does not explicitly name alternatives or state when not to use it, so it falls 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.
List the Defender for Endpoint alerts that involve a domain.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| domain | Yes | Domain name. | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint, openWorldHint, and destructiveHint=false annotations already establish the safety profile. The description adds no behavioral nuance such as how 'involve' a domain is matched, whether pagination is used, or how the filter affects the result set. It is simply a restatement of the tool's basic operation.
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?
A single, front-loaded sentence states the action, resource, and scope with no filler. It earns its place and leaves no redundant text.
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 simple list operation with complete parameter schemas and readOnly annotations, the description is minimally viable. It does not describe what fields the returned alerts will contain, what domain matching means, or how the OData filter interacts with the domain parameter, but the core call can be constructed correctly from the schema and description.
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 input schema already covers 100% of the parameters with useful descriptions for top, domain, and filter. The tool description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 applies.
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 uses a clear verb ('List') with a specific resource ('Defender for Endpoint alerts') and a domain scope, which is distinct enough to separate it from get_domain_machines or get_domain_statistics. It does not explicitly compare against sibling tools, so it stops short of a 5.
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 context is implied: use this tool when you need alerts related to a given domain. However, there is no mention of when to prefer it over sibling alert tools such as defender_get_file_alerts or defender_get_ip_alerts, nor any guidance on when a different domain-focused tool would be better.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices that communicated with a domain: the lateral scope of a domain.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 100). | |
| domain | Yes | Domain name. | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations provide readOnlyHint=true and destructiveHint=false, so the description doesn't need to restate safety. However, the description fails to disclose other behavioral aspects: the meaning of 'communicated' (e.g., does it include historical or only current connections?), whether the result is a list of machine objects or just IDs, and any potential pagination or performance implications. The description adds minimal context beyond the one-liner.
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 a single sentence that is concise and front-loads the core purpose. It efficiently adds the 'lateral scope' insight without waste. It could be slightly more informative, but it's well-structured.
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 tool has 3 parameters (1 required) and no output schema. The description is minimal and doesn't explain the return format (e.g., list of machine objects with properties), any common use cases, or how 'filter' refines results. However, given the simplicity and full schema coverage, it's adequately complete for basic invocation, but misses nuances like how 'top' interacts with 'filter'.
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 already covers 100% of parameters with descriptions, so the baseline is 3. The description does not add extra meaning beyond what's in the schema; it doesn't clarify the 'filter' parameter's relationship to the 'top' parameter or the exact format of the filter. However, since schema coverage is complete, this is acceptable.
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 ('List') and resource ('devices that communicated with a domain'), which is clear. It also adds the helpful insight that this reveals the 'lateral scope of a domain,' distinguishing it from other domain-related tools like defender_get_domain_alerts or defender_get_domain_statistics. However, it doesn't explicitly name a sibling for differentiation, so it's not a 5.
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 implies when to use this tool (when you need to know which machines communicated with a domain, i.e., lateral scope) but does not explicitly state when not to use it or mention alternatives. For example, it doesn't contrast with defender_get_domain_alerts or defender_get_machines. This is adequate but leaves room for inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the prevalence of a domain in this organization, with first and last seen.
| Name | Required | Description | Default |
|---|---|---|---|
| domain | Yes | Domain name. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover the safety profile (readOnlyHint=true, destructiveHint=false). The description adds that the statistics are scoped to 'this organization' and include first/last seen timestamps, which is useful context beyond the schema. However, it doesn't disclose any other behavioral traits such as rate limits, data freshness, or the meaning of 'prevalence'. With annotations present, the added context earns a middle score.
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 a single compact sentence that front-loads the verb and resource, then adds scope and key output fields. There is no filler, redundancy, or unnecessary detail. Every word contributes to the meaning.
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 one well-documented parameter and no output schema, the description mentions output fields ('prevalence', 'first and last seen') but leaves 'prevalence' undefined—whether it is a count, percentage, or other metric. For a read-only statistics tool, an agent might benefit from knowing exactly what prevalence represents and the shape of the return value. The description is adequate but has a clear gap.
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 input schema fully documents the only parameter ('Domain name.'), so schema coverage is 100%. The description does not add any extra meaning about the parameter, such as format restrictions, case sensitivity, or examples. Per the rubric, full schema coverage sets a baseline of 3, and the description does not exceed 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?
The description states a specific verb and resource ('Get the prevalence of a domain') and scopes it to 'this organization', with output fields ('first and last seen'). It clearly distinguishes from sibling list-type tools like defender_get_domain_alerts or defender_get_domain_machines, but it does not explicitly name or contrast alternatives, so it stops short of a 5.
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 implies when to use the tool (when you need domain prevalence statistics) but provides no explicit guidance about alternatives or when not to use it. There is no mention of preferring this over defender_get_domain_alerts or defender_get_domain_machines for different needs. Usage context is only implied by the purpose statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the organization's exposure score: lower is better.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds the interpretive detail that lower is better, but does not disclose score range, freshness, or rate-limit behavior. This is acceptable given the annotations, but not particularly rich.
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 a single sentence with no filler, and the core action is front-loaded before the interpretive note. Every word 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?
For a zero-parameter, read-only tool, the description is complete enough for an agent to invoke it correctly. The scope ('organization') is clear, the evaluation direction is provided, and no output schema or parameter details are required.
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?
There are zero parameters, so the input schema needs no explanation. The description adds no parameter-level details, but none are needed for invocation.
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 clearly states the action ('get') and the resource ('the organization's exposure score'), which distinguishes it from machine-group-specific exposure scoring among the siblings. The addition of 'lower is better' provides useful interpretation, though it does not explicitly contrast with defender_get_secure_score.
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?
No guidance is given about when to prefer this over sibling tools like defender_get_secure_score or defender_get_machine_group_exposure_score. The context implies organization-level scope, but the description does not explicitly state exclusions or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Defender for Endpoint alerts that involve a file.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| file_hash | Yes | SHA1 or SHA256 of the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish readOnlyHint=true and destructiveHint=false, and the description does not contradict them. It adds little beyond that safety profile, such as pagination behavior or what 'involve a file' means in alert terms; no contradiction exists.
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?
One short sentence that leads with the action and scopes the resource; no filler or duplication of schema content.
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-only list operation with one required, well-specified hash parameter, the description is sufficient for selection and invocation. It does not describe the output shape, but no output schema exists and 'list' reasonably implies a collection of alert objects.
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?
All three parameters are already documented in the schema (file_hash as SHA1/SHA256, top default/max, filter as OData expression), so the description need not repeat them. The phrase 'involve a file' maps to file_hash without adding new semantic detail.
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 uses the specific verb 'List' plus the resource 'Defender for Endpoint alerts that involve a file,' which cleanly separates it from sibling alert-list tools scoped to domain, IP, user, or machine. It could name a sibling explicitly, but the file scope is 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?
The file-scoped phrasing implies the use case (alerts tied to a file), but the description does not explicitly say when to prefer this over defender_get_domain_alerts, defender_get_ip_alerts, defender_get_user_alerts, or defender_get_machine_alerts. No when-not-to-use or alternative guidance is present.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get what Defender knows about a file by hash: global prevalence and first seen, size, type, signer and issuer, determination. Only the hash leaves the environment.
| Name | Required | Description | Default |
|---|---|---|---|
| file_hash | Yes | SHA1 or SHA256 of the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only and non-destructive. The description adds valuable context beyond the annotations: the user-visible privacy guarantee that only the hash leaves the environment, and the specific knowledge fields returned. This helps an agent understand both the data scope and the side-effect profile, with no contradiction to the 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?
The description is two sentences with no filler. The action is front-loaded, the response fields are listed in a compact series, and the privacy caveat is appended as a separate, purposeful sentence. Every word contributes to call success or expectation-setting.
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 a single required parameter, fully documented schema, and strong annotations, the description supplies enough to call the tool: it enumerates the returned fields and notes the data-handling behavior. A minor gap is that the concept of 'determination' is not elaborated, and there is no explicit error or empty-result explanation, but given the tool's simplicity this is not a serious omission.
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 input schema already documents file_hash as 'SHA1 or SHA256 of the file' with 100% coverage, so the description does not need to restate it. The description does imply the hash is used to look up file intelligence, but it adds no fresh parameter-specific details beyond the schema, meriting the baseline score.
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 uses a specific verb ('Get'), identifies the resource ('what Defender knows about a file') and the key input ('by hash'), and enumerates the exact fields returned (prevalence, first seen, size, type, signer, issuer, determination). This differentiates it clearly from sibling tools like defender_get_file_alerts or defender_get_file_machines, which address different aspects of a file.
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 implies this tool is for general file intelligence by hash, and the privacy note ('Only the hash leaves the environment') hints at a data-handling consideration. However, it does not explicitly state when to use this tool instead of nearby alternatives such as defender_get_file_statistics or defender_get_file_alerts, nor does it mention any exclusions or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices a file was seen on: the lateral scope of a hash.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| file_hash | Yes | SHA1 or SHA256 of the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no extra behavioral detail such as pagination, authentication needs, or output shape, but the read-only intent is clear and consistent with the 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?
The description is one economical sentence with no filler. The primary action and resource are front-loaded, and the 'lateral scope' phrase adds useful investigative context without bloating the text.
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 simple read-only lookup with one required parameter and a fully documented schema, the description is sufficient to guide selection and invocation. It lacks an explicit statement about what fields the returned device list contains, and there is no output schema, but the core intent and scope are complete.
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 100%, so file_hash, top, and filter are already well documented. The description's 'file...hash' wording maps to file_hash and 'lateral scope' adds some semantic framing, but it does not significantly enhance parameter understanding 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?
The description states a specific verb ('List'), resource ('devices a file was seen on'), and explanatory phrase ('lateral scope of a hash'). This clearly distinguishes the tool from siblings like defender_get_file_info, defender_get_file_statistics, or defender_get_machines.
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 phrase 'devices a file was seen on' and 'lateral scope' clearly signals the use case: investigating where a particular hash has appeared across devices. It does not explicitly name alternatives or exclusion conditions, 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.
Get the prevalence of a file in this organization and worldwide, with first and last seen. A file seen on one device and nowhere else is worth a closer look.
| Name | Required | Description | Default |
|---|---|---|---|
| file_hash | Yes | SHA1 or SHA256 of the file. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds useful behavioral scope—organization-wide and worldwide prevalence plus first/last seen—but does not describe response shape, zero-result behavior, or pagination. With annotations carrying safety, this is adequate but not rich.
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?
Two short, purposeful sentences. The first states the core function and scope, and the second adds actionable triage context. There is no repetition of schema or annotation information and no wasted words.
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 one-parameter, read-only tool with no output schema, the description is complete enough: it tells the agent what kind of data is returned (prevalence, first/last seen) and why that data matters. It could name exact return fields, but the simplicity of the operation does not demand much more.
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 100%, and the single parameter file_hash is fully described as 'SHA1 or SHA256 of the file.' The description adds no hash-specific semantics beyond referring to 'a file,' so it does not need to compensate for schema gaps. Baseline 3 is appropriate.
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 a specific verb ('Get'), resource ('file'), and scope ('prevalence in this organization and worldwide, with first and last seen'). This clearly distinguishes it from file-focused siblings like defender_get_file_info, defender_get_file_alerts, and defender_get_file_machines.
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 for use: it returns prevalence data and first/last seen, and the heuristic 'a file seen on one device and nowhere else is worth a closer look' signals a threat-triage use case. It doesn't explicitly name alternatives or when-not-to-use, but the context is unambiguous enough for a simple read-only stats tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one incident as it is stored: severity, status, classification, determination, owner, custom tags, comment thread, timestamps, and redirectIncidentId when it was merged into another. The starting point of incident analysis; it does not follow merges (use defender_resolve_incident for that).
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only and non-destructive behavior; the description adds beyond that by clarifying it returns the raw stored incident, mentioning redirectIncidentId when merged, and explicitly noting the tool does not traverse merge relationships. No contradiction with 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?
The description is dense but efficient: it front-loads the field list, then adds the two most important operational details—starting-point role and merge limitation—without filler. 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?
For a single-parameter, read-only fetch with no output schema, the description is complete: it covers what the tool returns, when to use it, and the one important caveat (merge behavior). No critical gap remains for correct invocation.
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 fully describes incident_id with 100% coverage, so the description adds no additional parameter semantics. Baseline 3 applies because the schema already carries the parameter meaning.
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 clearly states a specific verb ('Get') and resource ('one incident as it is stored'), then enumerates the exact fields returned. It also distinguishes itself from merge-following behavior, which helps separate it from siblings like defender_resolve_incident.
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 explicitly positions the tool as 'the starting point of incident analysis' and gives a concrete when-not-to-use condition: 'it does not follow merges', directing the agent to defender_resolve_incident instead. This is an explicit when/when-not/alternative pairing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the alerts of an incident, paged (skip/top), with their details: title, severity, category, MITRE techniques, detection source, timestamps and nested evidence. For the entities themselves prefer defender_get_incident_evidence, which flattens and de-duplicates the evidence of every alert in one call.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 10, max 50). | |
| skip | No | Number of entries to skip (paging). | |
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. | |
| summary_only | No | Only id, title, severity, category, status, detector, MITRE techniques and timestamps, without the evidence. Recommended first call on a large incident. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond annotations: paged results, nested evidence, and that the evidence tool flattens/de-duplicates. Minor gap: it does not describe response size or trailing pagination details, but annotations cover the safety profile.
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?
Two sentences with no fluff. The first is front-loaded with the core action and return detail; the second is an actionable pointer to the sibling tool.
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 is complete for a read-only paged list tool. It covers what is returned, how paging works, and which alternative to use for a different need. The schema covers parameter details, and annotations cover the read-only/destructive safety profile.
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 100%, and each parameter already has a meaningful description. The tool description adds complementary context about paging and nested evidence but does not materially improve parameter semantics beyond what the schema provides.
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 clearly states the tool gets an incident's alerts, lists the exact fields returned, and explicitly contrasts it with defender_get_incident_evidence. It distinguishes itself from siblings without needing to open schemas.
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 explicit routing: for entities/evidence, prefer defender_get_incident_evidence. It also communicates pagination semantics via skip/top, giving an agent clear guidance on when and how to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
The full evidence inventory of an incident: the portal's evidence view as one table. Pages
through every alert and flattens the evidence into one row per evidence item, each joined to
its device (by device ID, else through the alert) and listing the alerts that cite it. A row
is the source's own unit: entityCount equals the portal's count of evidence items and is the
number to reconcile; rowCount is the number of per-alert evidence rows. The source lists one
process more than once when alerts describe it differently (no image file, another path, a
different verdict): those rows share instance (device, PID, creation time), sameProcess
groups them with their verdicts, and processInstanceCount is the number of real processes.
Rows carry type, name, PID and parent PID, full command line and its decoded
-EncodedCommand payload, creation times in UTC, SHA1/SHA256, path, user SID and UPN, device
ID, IP, registry key and value, detailed roles, verdict and remediation status. Follows a
merged incident to its master. These are the entities the alerts cite, not raw telemetry:
processes the detection did not flag are not here.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of entities to return (default 200, max 1000). | |
| skip | No | Number of entries to skip (paging). | |
| types | No | Only these entity types, e.g. ['process', 'file']. Types: device, user, process, file, ip, url, registry_key, registry_value, mailbox, and any other evidence type the source reports. entityCount always covers the whole incident. | |
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description goes far beyond the annotations (which are already read-only and open-world) by disclosing page-through/flattening behavior, entityCount vs rowCount semantics, duplicate row handling via instance/sameProcess/processInstanceCount, merged-incident following, and the fact that it only includes flagged entities, not raw telemetry. This is rich behavioral context that a caller needs to interpret results correctly.
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 a dense paragraph, but every sentence contributes substantive information — flattening, deduplication, field inventory, merged incidents, and exclusions. It is not redundant, though better visual structure (bullets or headings) could improve scannability for a tool with this much behavioral nuance.
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 this is a complex tool with no output schema, the description compensates well by explaining return semantics (entityCount, rowCount, processInstanceCount), the row unit, deduplication logic, and the difference from other incident data. It covers all the essential information an agent needs to call the tool and interpret its response, within the context of the provided annotations.
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 input schema has 100% coverage for all parameters (top, skip, types, incident_id), including defaults and descriptions. The tool description does not add parameter-specific semantics beyond what the schema already provides, so the baseline of 3 applies.
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 clearly states the tool returns the full evidence inventory of an incident as the portal's evidence view, with a specific verb/resource combination and detailed scoping. It distinguishes itself from sibling tools like defender_get_incident or defender_get_incident_alerts by focusing on flattened per-evidence rows with entities, not just alerts.
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 context on what the tool returns (evidence entities, not raw telemetry) and how it behaves with merged incidents, which implies when it is useful. However, it does not explicitly name alternatives or state when to prefer this over defender_get_incident_alerts or other sibling tools, so the guidance is implicit rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the custom indicators (allow, audit, warn, block) of the tenant, with OData filtering, e.g. "indicatorValue eq '203.0.113.7'", "action eq 'Block'".
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of indicators to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering the safety profile. The description adds useful context about the indicator types and OData filtering examples, but does not disclose additional behavioral traits such as pagination limits or potential result size beyond what the schema already specifies.
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 a single, focused sentence that front-loads the core action and resource, then adds filtering details and examples. It is concise with no wasted words, earning a high score for efficiency.
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 tool's simplicity (3 optional parameters, all documented) and the presence of annotations covering safety, the description is fairly complete. It explains what is listed, the filtering capability, and provides examples. While it doesn't describe the return format, that is not required given the lack of an output schema and the straightforward nature of a list operation.
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 100%, so the baseline is 3. The description adds value by providing concrete OData filter examples ('indicatorValue eq ...', 'action eq ...'), which clarifies how to use the filter parameter beyond its generic schema description. This enriches the 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?
The description clearly states the verb 'List' and the resource 'custom indicators of the tenant', specifying the indicator types (allow, audit, warn, block) and the filtering capability. It distinguishes itself from sibling tools by being the only one dealing with indicators.
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 implies usage when one needs to list custom indicators, but it does not explicitly mention when to use this tool over other 'defender_get_*' tools or any exclusions. No alternatives are named, so the usage context is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one automated investigation: state, status details, device and triggering alert.
| Name | Required | Description | Default |
|---|---|---|---|
| investigation_id | Yes | The investigation ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description is consistent with that safety profile. It adds context about the returned fields (state, status details, device, triggering alert) but does not disclose any additional behavioral traits such as permissions, rate limits, or error behavior. This meets the baseline given annotation coverage.
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 a single, information-dense sentence. It front-loads the action and resource, lists the key return contents, and contains no filler or redundant wording.
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 one-parameter read-only getter with no output schema, the description adequately lists the primary return components. It does not mention how to obtain the investigation_id or potential errors, but these are secondary for a simple retrieval tool. The description is sufficiently complete for the tool's complexity.
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 already provides 100% coverage for the single parameter investigation_id with 'The investigation ID.' The description adds no extra semantics about the ID format, source, or usage beyond the schema, so the baseline score of 3 is appropriate.
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 exactly what the tool does: retrieves a single automated investigation with its key components (state, status details, device, triggering alert). The singular 'one' and 'automated investigation' distinguish it clearly from sibling tools like defender_get_investigations and defender_get_incident.
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?
No explicit guidance is provided on when to use this tool versus alternatives. There is no mention that this is the by-ID variant of defender_get_investigations or that listing investigations requires the plural version. The implication from 'one' is weak and not a substitute for clear routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List automated investigations with their state and the alert that triggered each.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of investigations to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds that results include investigation state and triggering alert, which is useful. However, it does not disclose pagination behavior, default ordering, or whether the filter supports OData syntax beyond the schema's mention.
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?
One sentence, front-loaded with the verb and resource, and it includes the most important output context (state and triggering alert). No wasted words.
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 simple list tool with full schema coverage and read-only annotations, the description is mostly adequate. However, it lacks any mention of pagination behavior, default ordering, or how the filter parameter interacts with paging—details an agent might need for correct invocation. The output schema is absent, so a bit more return-format context would help.
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 100%, so the schema already documents all three parameters (top, skip, filter) with defaults and meanings. The description adds no additional parameter semantics beyond what the schema provides, so baseline 3 is appropriate.
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 ('List'), a resource ('automated investigations'), and the key returned data ('state and the alert that triggered each'). It is clear and distinguishes from the sibling defender_get_investigation_by_id (which fetches a single investigation), though it doesn't explicitly name that sibling.
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 implies a read/list use case but does not state when to prefer this over defender_get_investigation_by_id or other investigation-related tools. The filter parameter hints at refining results, but no explicit when-to-use or alternative guidance is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Defender for Endpoint alerts that involve an IP address.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IP address. | |
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the IP-involvement scoping, but does not clarify behavioral details such as whether IP can be source/destination or how results are structured.
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?
A single front-loaded sentence that states exactly what the tool does. There is no filler, redundancy, or unnecessary repetition of schema details.
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 simple read-only list with full schema coverage, this is mostly adequate. However, it lacks sibling-routing guidance and does not explain what 'involve an IP address' means operationally, leaving some ambiguity.
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 100%, and the schema already documents ip, top, and filter with type and limits. The description adds no significant parameter meaning beyond restating the IP criterion, so baseline 3 is appropriate.
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 uses a specific verb ('List') and names the exact resource ('Defender for Endpoint alerts') plus the IP scoping criterion. It is clearly distinguishable from sibling tools like defender_get_domain_alerts or defender_get_user_alerts.
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?
No explicit guidance is given about when to use this tool versus the many sibling alert-list tools. The IP criterion is implied, but there is no when-to-use, when-not-to-use, or alternative routing information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the prevalence of an IP address in this organization, with first and last seen.
| Name | Required | Description | Default |
|---|---|---|---|
| ip | Yes | IP address. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the description isn't required to restate that. It adds the scope ('in this organization') and the return fields (first and last seen), but does not disclose how prevalence is computed, whether results are bounded, or any permission/rate-limit context. That is moderate value beyond annotations, so a 3 is appropriate.
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 a single, front-loaded sentence. It states the operation, object, scope, and additional output in 15 words, with no redundant phrases.
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 output schema URL, the description carries the burden of explaining the return value. It mentions prevalence and first/last seen, but 'prevalence' is left ambiguous (count? percentage? affected machines?), and there is no mention of time ranges, pagination, or unsupported IP formats. For a simple one-parameter read-only tool this is only mildly incomplete, so a 3.
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 100%: the only parameter, 'ip', is already described in the schema as 'IP address.' The tool description merely repeats 'IP address' without adding format constraints (e.g., IPv4 vs IPv6), normalization, or matching behavior. Baseline 3 applies.
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 uses a specific verb and resource ('Get the prevalence of an IP address') and adds scope ('in this organization') plus return details ('with first and last seen'). It clearly distinguishes from sibling tools like defender_get_ip_alerts or defender_get_file_statistics, which focus on different data.
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 no guidance on when to use this tool over alternatives. It does not name sibling tools or conditions (e.g., 'use defender_get_ip_alerts for IP-related alerts'). The usage context is only implied by the tool's name and the phrase 'in this organization', which isn't enough given the large sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the short-lived download link of the output of one live response command.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes | The machine action ID. | |
| command_index | Yes | Index of the command (0-based). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds the useful behavioral detail that the link is short-lived and tied to a single command index, but provides little else (no expiration duration, no return format). No contradiction with 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?
One concise sentence, front-loaded with the verb and resource, containing no filler words or repeated schema information. Every word contributes to the 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?
Given the tool's simplicity (2 read-only parameters, no output schema), the description sufficiently conveys what the caller receives (a short-lived download link) and the key caveat (short-lived). Minor omissions like response envelope or exact expiration time are not essential for correct invocation.
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 100% for both required parameters, and the descriptions ('The machine action ID.' and 'Index of the command (0-based).') are adequate. The tool description itself adds no further parameter semantics 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?
States a specific action ('get the short-lived download link') and a distinct resource ('output of one live response command'). Unambiguously differentiates it from the many other defender_get_* sibling tools and from generic retrieval tools.
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 no guidance on when to use this tool versus alternatives, nor any prerequisites such as needing an action_id from a live-response session. The description only states the operation, leaving an agent to infer the timing and context of a call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one machine action: type, status (Pending, InProgress, Succeeded, Failed, TimeOut, Cancelled), requestor, comment and times. Poll it after a response action.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes | The machine action ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds the polling hint and enumerates the returned status values, which is genuinely useful behavioral context. It does not describe pagination or error behavior, but for a single-resource GET that is a minor 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?
Two sentences: the first front-loads what the tool returns, the second gives the operational use case (polling). No wasted words, no fluff.
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 simple single-parameter read-only retrieval tool with full schema coverage and safety annotations, the description is nearly complete. It omits only minor details like the output shape, but no output schema exists and the enumerated statuses in the description partly compensate. The polling guidance completes the operational picture.
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 100% for the single action_id parameter, so the schema carries the parameter meaning. The description adds no extra parameter semantics beyond identifying the resource being fetched. Baseline 3 is appropriate.
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 clearly states the tool gets a single machine action and lists the fields it returns (type, status, requestor, comment, times). This distinguishes it from the sibling defender_get_machine_actions (plural) by the explicit singular 'one machine action'. A 5 would require naming the sibling explicitly, which it does not do.
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 instruction 'Poll it after a response action' gives a clear when-to-use context and implies repeated polling. It does not explicitly say when not to use it or name defender_get_machine_actions as the alternative for listing actions, so it stops just 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.
List response actions taken on devices (isolation, release, scans, quarantine, packages, live response) with their status, requestor, comment and times, e.g. filter "machineId eq ''" or "type eq 'Isolate'". It lists actions taken by anyone, people included, so it is how to check whether a containment still stands.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of actions to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover readOnlyHint=true and destructiveHint=false, so the description only needs to add context beyond that. It does so by noting the tool shows actions taken by anyone and that it is the way to verify containment status. It doesn't discuss paging behavior or response shape, but those are less critical given the annotations and schema-covered parameters.
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 behavior is front-loaded, followed by filter examples and then a use case. It is dense and every clause contributes information, though the final 'so it is how to check whether a containment still stands' is phrased a bit informally.
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 read-only annotations, fully documented parameters, and no output schema, the description provides enough context: what actions are returned, what fields appear, how to filter, and when an agent should use this tool. Nothing essential for selecting and invoking it 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 100%, so the baseline is a 3. The description adds value with concrete OData filter examples ('machineId eq \'<id>\'', 'type eq \'Isolate\''), giving agents usable syntax beyond the schema's generic 'OData $filter expression'.
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 ('List') and resource ('response actions taken on devices'), enumerates the action types (isolation, release, scans, quarantine, packages, live response) and the fields returned (status, requestor, comment, times). The plural 'actions' and the 'List' wording clearly differentiate it from the sibling tool defender_get_machine_action_by_id.
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 use case: 'it is how to check whether a containment still stands'. Also provides practical filter examples with machineId and type. It does not explicitly name alternatives or state when not to use it, so it stops slightly short of full exclusion guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Defender for Endpoint alerts of one device.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| machine_id | Yes | The Defender for Endpoint machine (device) ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the device-scoping behavior but does not disclose response format, pagination behavior, or other operational details beyond what the schema and annotations already provide.
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?
A single sentence with no filler: it front-loads the action, resource, and scope. Every word contributes to the core purpose, making it a model of concise and well-structured tool documentation.
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 simple read-only list tool with a fully described schema and safety annotations, the description is adequate to identify purpose and scope. The only gap is the lack of an output schema or explicit statement of returned alert fields, but the name and sibling tools make the return type predictable.
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 100%, so the parameters (machine_id, top, filter) are already fully documented. The description does not add meaning beyond reinforcing that alerts are machine-scoped, which aligns with the baseline of 3 when the schema carries the semantic weight.
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 ('List'), the resource ('Defender for Endpoint alerts'), and a scoping qualifier ('of one device'), which clearly distinguishes it from sibling tools like defender_list_alerts (all alerts) and defender_get_alert (single alert). The purpose is immediately 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?
The description implies the tool is for retrieving alerts for a specific device, but it gives no explicit when-to-use guidance or alternatives. The phrase 'of one device' provides context, yet an agent must infer when to choose this over defender_list_alerts or other machine-focused tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one device: DNS name, OS, health, risk and exposure level, tags, device value, IPs, first and last seen. Accepts the machine ID (the mdeDeviceId of alert evidence).
| Name | Required | Description | Default |
|---|---|---|---|
| machine_id | Yes | The Defender for Endpoint machine (device) ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already establish read-only and non-destructive behavior. The description adds value by specifying the exact response content (DNS name, OS, health, risk, exposure, tags, IPs, timestamps), which is especially useful because there is no output schema. It does not cover error/not-found behavior, but annotations lower the bar.
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?
Two tightly packed sentences: the first states the action and result fields, the second tells the agent where the ID comes from. No filler or repeated schema content.
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 one-parameter read-only lookup with no output schema, this description is complete: it identifies the resource, the required input, and the returned fields. The annotations cover the safety profile, so nothing essential 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 schema already describes machine_id at 100% coverage. The description adds the key semantic that this is the mdeDeviceId from alert evidence, which tells an agent exactly where to obtain the value.
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 uses a specific verb and resource ('Get one device') and enumerates the returned fields, making it unmistakably a single-device lookup by ID. This distinguishes it from sibling bulk/collection getters like defender_get_machines and find helpers.
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 usage context: use this when you have a machine ID, specifically the mdeDeviceId from alert evidence. It does not explicitly name alternatives or 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.
Get the exposure score of each device group.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark this as read-only and non-destructive, so the description adds no new safety context. The description states it retrieves scores but does not disclose the return structure (e.g., list of group objects with score fields) or any potential access requirements, which are not covered by 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?
The description is a single, concise sentence that communicates the essential action and resource. All information is front-loaded with no redundant or filler words, making it highly efficient.
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 tool's simplicity (no parameters, no output schema, read-only annotations), the description is minimally sufficient. However, it does not specify the exact format of the returned data, such as whether it returns a list of group identifiers with numeric scores, which could leave ambiguity for an agent without additional context.
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 has zero parameters, and the schema coverage is 100%. Per the baseline for 0-parameter tools, a score of 4 is appropriate; the description does not need to explain parameters that do not exist.
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 ('Get') and resource ('exposure score of each device group'), clearly indicating a per-group listing. It could more explicitly distinguish from defender_get_exposure_score (which likely returns a global score) but the name and description make the primary purpose 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?
No guidance is provided on when to use this tool versus alternatives like defender_get_exposure_score or defender_get_secure_score. An agent is left to infer that this is for per-group scores, but there is no explicit differentiation or condition for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the users that logged on to a device.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of users to return (default 25, max 200). | |
| machine_id | Yes | The Defender for Endpoint machine (device) ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds no additional behavioral detail, such as pagination, ordering, or what constitutes a 'logon'. It is consistent with annotations but does not extend them.
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 a single, clear sentence with no unnecessary words. The action and target are front-loaded, making it easy to scan and parse quickly.
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 simple read-only list operation with two parameters fully documented in the schema, the description is adequate. It lacks details on return format or edge cases, but given the simplicity and annotation coverage, it is reasonably complete.
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 100%: both machine_id and top have descriptions in the schema, including defaults and maximums. The description adds no extra meaning beyond the schema, so the baseline score of 3 is appropriate.
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 clearly states the action (list), the resource (users), and the scope (logged on to a device). It is specific enough to distinguish from sibling tools like defender_get_machine_alerts or defender_get_user_machines, which concern different entities.
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 no guidance on when to use this tool versus alternatives. There are many get_* tools in the sibling list, and this one is not differentiated in terms of use cases, prerequisites, or exclusions. An agent would have to infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List devices onboarded to Defender for Endpoint, with OData filtering, e.g. "healthStatus eq 'Active'", "riskScore eq 'High'", "startswith(computerDnsName,'ws')".
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and openWorldHint=true, so the safety profile is covered. The description adds concrete OData filter examples (healthStatus, riskScore, startswith on computerDnsName), which gives agents actionable knowledge beyond the annotations. It doesn't contradict 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?
The description is a single concise line followed by three illustrative examples. It's front-loaded with the verb and resource, every word earns its keep, and the example filter expressions are tightly relevant. No unnecessary elaboration.
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 output schema, the description could mention that it returns a list of machine objects, but 'List devices' implies that. The combination of description and schema covers what it lists, how to filter, and paging via top/skip. A note on return shape would be a minor addition, not a critical gap.
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 100%, so each parameter (top, sKip, filter) is already well-documented. The description adds value by showing exact syntax for the filter parameter, which helps an agent construct valid queries rather than just knowing the schema type. This goes beyond the baseline.
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: 'List devices onboarded to Defender for Endpoint'. The OData filter examples clarify it's the general machines list, not a filtered-by-vulnerability or software list. It doesn't explicitly distinguish from sibling tools like defender_get_machine_by_id, but the naming and verb 'List' make the core purpose 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 implies use when you need a list of machines with OData filtering, and provides realistic filter examples, but it doesn't state when not to use it or mention alternatives such as defender_get_machines_by_vulnerability or defender_find_machines_by_tag. There is no explicit exclusion or routing guidance for the sibling set.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices that have a software installed.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 200). | |
| software_id | Yes | The software ID, e.g. microsoft-_-edge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond restating the list operation; it does not mention pagination, result ordering, or that the result is a machine list. This is acceptable but not additive.
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 a single concise sentence with no filler. It front-loads the action and object, though the awkward phrasing 'a software' slightly reduces polish. It earns its place without burdening the agent.
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 simple two-parameter read-only list tool, the description and schema together are mostly sufficient. However, the absence of usage guidance and the lack of any note about the return shape or pagination leave minor gaps, especially without an output schema. The description is adequate but not complete.
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 100%, with both 'top' and 'software_id' documented in the input schema. The description adds little semantic value beyond the schema, but none is really needed. Baseline 3 is appropriate.
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 clearly states a specific action ('List the devices') and the resource ('devices that have a software installed'), which distinguishes it from vulnerability-focused siblings like defender_get_machines_by_vulnerability. However, it could more explicitly name the parameter (software_id) as the filter key, and the phrasing 'a software' is slightly vague.
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 no guidance on when to choose this tool over alternatives such as defender_get_machines, defender_get_machines_by_vulnerability, or defender_get_software. There is no mention of when this tool is appropriate or when a sibling would be better, leaving the agent to infer usage solely from the name and parameters.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices exposed to a vulnerability.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 200). | |
| cve_id | Yes | The CVE ID, e.g. CVE-2024-1234. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds no behavioral context beyond the annotations. It simply restates a listing operation; no pagination behavior, rate-limit implications, or other non-obvious traits are disclosed. It does not contraddict the readOnly/openWorld annotations, but it also contributes nothing extra.
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 a single, front-loaded sentence with no filler. Every word earns its place and the core behavior is immediately clear.
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 simple read-only lookup, the description plus schema is mostly complete. However, with no output schema, the description does not indicate the shape or cardinality of the returned device list, and it does not help an agent choose among the many similar sibling tools.
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 100%, so the description does not need to document parameters. It adds no extra semantic detail beyond the schema, which is acceptable under the baseline for high schema coverage.
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 clear verb and resource: 'List the devices exposed to a vulnerability.' It conveys the core operation without being vague, though it does not explicitly differentiate itself from sibling tools like defender_get_machines_by_software or defender_get_recommendation_machines.
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?
No guidance is given about when to use this tool instead of sibling vulnerability-, machine-, or recommendation-focused tools. The intended usage is only implied by the tool name and short description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vulnerabilities that affect one device.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of vulnerabilities to return (default 25, max 200). | |
| machine_id | Yes | The Defender for Endpoint machine (device) ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is established. The description adds the one-device scoping but does not disclose details about pagination, result limits beyond the schema, or any special behavior. With annotations covering the safety profile, this is adequate but not enriched.
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 a single, focused sentence with no filler. The key scope ('one device') is front and center.
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 simple read-only list operation with two well-documented parameters and no output schema, the description provides sufficient context to invoke the tool. It could slightly improve by naming the alternative for global vulnerability listing, but overall it is complete enough.
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 100%, so both parameters are already documented. The description adds a conceptual link between 'one device' and machine_id but does not provide additional semantics beyond what the schema gives. Baseline 3 applies.
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 uses a specific verb ('List') and a specific resource ('vulnerabilities that affect one device'), making it immediately distinct from broader tools like defender_get_vulnerabilities or defender_get_software_vulnerabilities. The 'one device' scope clearly matches the required machine_id parameter.
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 states the tool is for a single device, which implies use when you have a machine_id and need its vulnerabilities. It does not explicitly name alternatives or provide exclusion criteria, but the scope is clear enough for selection among many sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the short-lived download link of a collected investigation package. The link grants access to forensic data: hand it to a person, do not store it in a note.
| Name | Required | Description | Default |
|---|---|---|---|
| action_id | Yes | The machine action ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark it read-only and non-destructive. The description adds important behavioral context: the link is short-lived, grants access to sensitive forensic data, and should not be persisted. This goes beyond what annotations convey, though it doesn't specify expiration length or response format.
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?
Two concise sentences with no filler. The first states the tool's purpose, and the second adds essential security guidance. Every sentence earns its place and the key action is front-loaded.
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 one-parameter tool with no output schema, the description gives enough to act: it names the resource, the parameter is documented in the schema, and it warns about the sensitive nature of the result. A small gap is that it doesn't explicitly say the returned value is a direct URI string, but 'download link' strongly implies this.
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 100%: the single required parameter action_id is already described as 'The machine action ID.' The description adds no extra parameter-level meaning, so the schema carries the burden and the baseline of 3 applies.
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: getting the short-lived download link of a collected investigation package. This clearly distinguishes the tool from the many sibling get_* tools, none of which produce a package download link.
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 context is clear: use this after an investigation package is collected, to obtain a shareable link. It also gives handling instructions—hand to a person, do not store in a note—though it does not explicitly name alternative tools or exclusion conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one security recommendation.
| Name | Required | Description | Default |
|---|---|---|---|
| recommendation_id | Yes | The security recommendation ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds no behavioral context beyond the implied read operation, such as error behavior, null handling, or response shape, so it does not add value beyond the 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?
The description is extremely concise, with no filler or redundant wording. It is front-loaded and readable, though it borders on under-specification due to the absence of any usage context.
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 simple one-parameter, read-only getter with no output schema, the description is minimally adequate: it identifies the core action and resource. However, it lacks any context about alternatives or edge behaviors, which leaves the agent to infer the full selection logic from sibling names.
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 description covers 100% of the single parameter recommendation_id, so the baseline is 3. The description 'Get one security recommendation' provides no additional semantic detail about the parameter, but none is required beyond what the schema already states.
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 clearly states the action ('Get') and resource ('security recommendation'), with 'one' distinguishing it from the plural list tool defender_get_recommendations. It does not explicitly mention 'by ID' in the prose, but the tool name and recommendation_id parameter make the intent 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?
There is no guidance on when to use this tool versus alternatives such as defender_get_recommendations, defender_get_recommendation_machines, or defender_get_recommendation_vulnerabilities. No exclusion criteria or routing hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices a security recommendation applies to.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 200). | |
| recommendation_id | Yes | The security recommendation ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description's 'List' is consistent with a read-only operation. However, the description adds no behavioral context beyond that—no mention of pagination, error handling for invalid recommendation IDs, or what 'applies to' means in practice. With annotations covering the safety profile, this is acceptable but not enriched.
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 a single concise sentence that front-loads the primary action and object. Every word earns its place, with no extraneous details or redundant phrasing.
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 simple read-only list tool with fully documented parameters and safety annotations, the description is essentially adequate. The only minor gaps are the lack of detail about the returned device objects and the terminology mismatch between 'devices' in the description and 'machines' in the tool name, which could cause slight confusion.
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 100%; both top (with default and max) and recommendation_id are fully documented in the input schema. The description itself contributes no additional parameter meaning, so the baseline score of 3 is appropriate.
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: 'List the devices a security recommendation applies to.' It clearly identifies the tool as a getter for recommendation-affected machines. It doesn't explicitly differentiate from siblings such as defender_get_recommendation_vulnerabilities, but the resource is specific enough to avoid serious ambiguity.
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 no guidance on when to use this tool versus alternatives like defender_get_machines_by_vulnerability or defender_get_recommendation_vulnerabilities. The intended use case (given a recommendation_id, retrieve affected machines) is only implied, with no explicit conditions, exclusions, or alternative routing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List security recommendations, e.g. filter "remediationType eq 'ConfigurationChange'".
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of recommendations to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context beyond the annotations—no pagination behavior, response shape, or authentication notes. It neither contradicts nor enriches the 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?
The description is a single, front-loaded sentence that states the primary purpose immediately and then gives a useful example. No filler, redundancy, or unnecessary detail. Every word 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?
For a read-only list tool with three optional parameters, high schema coverage, and safety annotations, the description plus schema is sufficient for an agent to invoke it correctly. The filter example fills the main semantic gap. While no output schema means return fields are not specified, that is a minor omission given the straightforward listing purpose.
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 100% for all three parameters, so the baseline is 3. The description adds value by providing a concrete OData filter example ('remediationType eq ConfigurationChange'), illustrating how to use the filter parameter in practice. Top and skip are already well documented in 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 states a clear verb and resource: 'List security recommendations'. The concrete filter example ('remediationType eq ConfigurationChange') further clarifies the tool's scope. This clearly differentiates it from siblings like defender_get_recommendation_by_id, which targets a single recommendation.
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?
There is no guidance on when to use this tool versus alternatives like defender_get_recommendation_by_id, defender_get_recommendation_machines, or defender_get_remediation_activities. The filter example is parameter-level advice, not usage direction, and no exclusions or alternative selection hints are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vulnerabilities a security recommendation addresses.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of vulnerabilities to return (default 25, max 200). | |
| recommendation_id | Yes | The security recommendation ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds the scoping behavior that only vulnerabilities addressed by the recommendation are returned, but it does not describe pagination behavior, return shape, or any other runtime traits beyond that.
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 a single front-loaded sentence with no filler. It states the core action and object clearly, earning its place without redundancies.
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 simple read-only list tool with two well-documented parameters and safe annotations, the description is nearly complete. It could add a note about the returned vulnerability entities or the relationship to a parent recommendation, but nothing essential is missing for an agent to invoke 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 description coverage is 100%, so the schema fully documents both parameters. The description adds no additional meaning beyond what the input schema already provides for recommendation_id and top, so the baseline score of 3 is appropriate.
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 uses a specific verb ('List') and resource ('vulnerabilities a security recommendation addresses'), making the tool's function immediately clear. It also distinguishes itself from siblings like defender_get_recommendation_machines and defender_get_recommendation_by_id by naming the exact entity returned.
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 implies the use case: when you need the vulnerability details tied to a specific security recommendation. However, it gives no explicit guidance on when to prefer this over related tools such as defender_get_vulnerabilities or defender_get_recommendation_machines, and it names no alternatives or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List remediation activities with their status and due date.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of activities to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds that the result exposes status and due date, but it does not disclose pagination behavior, authorization requirements, or how the filter interacts with listing. There is no contradiction.
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?
One short sentence, front-loaded with the verb and resource. Every word earns its place; no repetitive or vague content.
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-only list with two documented parameters and annotations covering safety, the description is nearly sufficient. It mentions the key output fields, but it lacks any guidance on when to choose this tool over its remediation-specific siblings and does not describe response shape beyond fields. Still, the schema fills in the parameter gaps.
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 descriptions cover 100% of parameters (top and filter), so the baseline is 3. The description does not add any parameter semantics beyond the schema, and it doesn't mention how top/filter affect output. It is not misleading, just not additive.
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 uses a clear verb ('List') and identifies the resource ('remediation activities'), and it specifies the returned fields (status, due date). It distinguishes from the sibling defender_get_remediation_activity_by_id by implying a plural collection, but it does not explicitly call out scope or alternatives.
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?
There is no statement of when to use this tool versus alternatives such as defender_get_remediation_activity_by_id or defender_get_remediation_exposed_devices. The only guidance is the verb 'List,' which weakly implies collection-level queries. No exclusions or alternative routes are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one remediation activity.
| Name | Required | Description | Default |
|---|---|---|---|
| activity_id | Yes | The remediation activity ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. However, the description adds no behavioral context—it does not mention return type, pagination, authentication, or any side effects. With zero added behavioral info, the description falls short of the value expected beyond 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?
The description is a single sentence with no wasted words. It is front-loaded with the core purpose and appropriately concise for a simple retrieval tool. However, it is so brief that it omits context that could aid selection, slightly reducing the score.
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 large number of sibling tools, the description is incomplete for effective disambiguation. It does not explain what makes this tool distinct or when to prefer it over the plural variant or remediation-related tools. With no output schema and minimal description, an agent cannot fully determine the appropriate use case.
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 describes the single parameter 'activity_id' as 'The remediation activity ID.' with 100% coverage, so the baseline is 3. The description adds no additional meaning about the parameter, but for a single straightforward parameter, the schema 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 states a specific verb ('Get') and resource ('one remediation activity'), which clearly indicates it retrieves a single remediation activity. It does not explicitly name a sibling tool, but the use of 'one' distinguishes it from the plural 'defender_get_remediation_activities' without needing further detail.
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 no guidance on when to use this tool versus alternatives such as 'defender_get_remediation_activities' or 'defender_get_remediation_exposed_devices'. It does not mention prerequisites, context, or any exclusions, leaving the agent to infer usage from the parameter name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices still exposed under a remediation activity.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 200). | |
| activity_id | Yes | The remediation activity ID. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate that this is a read-only, non-destructive operation. The description adds a slight behavioral nuance by saying 'still exposed', which indicates the result filters to devices whose exposure persists, but it does not describe pagination, result ordering, or other operational behaior.
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 a single, concise sentence with no filler words. It is front-loaded and every part contributes to defining the tool's action, resource, and scope.
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 simple read-only listing tool with two well-documented parameters and no output schema, the description plus annotations and schema is sufficient. An agent can choose the tool and construct a valid call using activity_id and optional top without missing critical information.
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 100%, so both activity_id and top are already fully documented with types, defaults, and constraints. The description adds no parameter-level meaning beyond what the schema provides, meeting the baseline but not exceeding 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?
The description clearly states the action ('List') and resource ('devices still exposed under a remediation activity'). It is distinct from sibling tools that return remediation activities or remediation activity metadata, so an agent can tell what this tool returns.
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 phrase 'under a remediation activity' gives an implied usage context: the agent should call this after it has a remediation activity ID and needs remaining exposed devices. However, it does not explicitly say when to prefer this over related tools like defender_get_remediation_activity_by_id or defender_get_remediation_activities.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the Microsoft Secure Score for Devices: higher is better.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, covering safety and world-dependence. The description adds useful behavioral context beyond the annotations: the returned value is a device-scoped secure score and that higher values are better, which helps the agent interpret results correctly.
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 one short sentence that front-loads the verb and resource, then adds the key interpretation ('higher is better'). There is no repetition, padding, or unnecessary detail.
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 zero-parameter, read-only tool with no output schema, this description is nearly complete: it names the exact metric and tells the agent how to judge the result. It could slightly improve by noting the response shape or probable range, but that absence is minor given the tool's simplicity and the annotation coverage.
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?
There are zero parameters and the schema has no properties, so no parameter semantics are needed. The description additionally clarifies that the score applies to devices, which is the only input-relevant context. A baseline of 4 is appropriate for a parameterless tool.
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 clearly states the action ('Get') and the specific resource ('Microsoft Secure Score for Devices'), and adds the evaluative note 'higher is better.' It distinguishes itself from sibling metric tools like defender_get_exposure_score by naming the exact score type, though it does not explicitly contrast itself with any sibling.
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 implies the tool should be used when a caller wants the device secure score, but it gives no explicit guidance about when to prefer this over related scoring tools such as exposure_score or machine_group_exposure_score. There are no alternatives or exclusion criteria, so usage context is present only by inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the software inventory of the organization with weaknesses and exposed devices.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of software entries to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, covering the safety profile. The description adds that the inventory includes weaknesses and exposed devices, but says nothing about pagination, response size, or filtering behavior.
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?
A single sentence that is front-loaded with the action and resource, contains no filler, and is easy to scan. Every word adds 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?
Adequate for a simple read-only inventory listing with fully documented parameters and helpful annotations. However, there is no output schema and the description does not explain the return structure or provide usage differentiation among the many software-related sibling tools.
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 100%, so the schema fully documents the top, skip, and filter parameters. The description adds no parameter-level meaning beyond what the schema already provides, so baseline 3 is appropriate.
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 clearly states the action ('List') and resource ('software inventory of the organization'), and adds that results include weaknesses and exposed devices. It does not explicitly differentiate from siblings like defender_get_software_by_id, but the inventory-level scope is reasonably distinct.
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?
There is no guidance about when to use this tool versus the many related siblings such as defender_get_software_by_id, defender_get_software_vulnerabilities, or defender_get_machines_by_software. The description states what it does but not when to select it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one software entry: vendor, weaknesses, exploit availability, exposed devices.
| Name | Required | Description | Default |
|---|---|---|---|
| software_id | Yes | The software ID, e.g. microsoft-_-edge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds a useful list of returned fields, but it does not disclose the shape or granularity of weaknesses/exposed devices. No contradiction with 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?
The description is a single front-loaded sentence that lists both the resource and key fields without filler. Every word 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?
For a one-parameter read tool with no output schema, the description names the expected fields, but it leaves the return format ambiguous and does not clarify how this relates to sibling tools that return vulnerabilities/machines for a software.
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 100% and the software_id parameter includes an explicit example ('microsoft-_-edge'). The description adds no new parameter semantics, but with full schema coverage the baseline of 3 applies.
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 uses the specific verb 'Get' with the resource 'one software entry' and enumerates the key fields (vendor, weaknesses, exploit availability, exposed devices). It distinguishes from list-style siblings like defender_get_software via 'one', though it does not explicitly disambiguate from defender_get_software_vulnerabilities or defender_get_machines_by_software.
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?
There is no when-to-use guidance, no mention of alternatives, and no exclusion criteria. 'Get one software entry' implies usage when an ID is known, but the agent is not told when to prefer this over the many sibling software/vulnerability tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the distribution of installed versions of a software.
| Name | Required | Description | Default |
|---|---|---|---|
| software_id | Yes | The software ID, e.g. microsoft-_-edge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds the scoping to a single software's installed versions, but it does not disclose behavioral details like output shape, counts, or grouping semantics. Given annotation coverage, this is acceptable but minimal.
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 a single, focused sentence with no filler. The key concept 'distribution of installed versions of a software' is front-loaded and every word contributes to meaning.
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 one-parameter, read-only tool, the description states the operation and object sufficiently for an agent to select and invoke it. It does not describe the precise return shape of the distribution, but the simplicity of the tool and the absence of an output schema make this a minor gap rather than a serious omission.
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 100% and the single parameter includes an example ('microsoft-_-edge'), so the structured data carries the semantic load. The description adds no extra parameter-level detail, but none is required given the high schema coverage.
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 a specific operation ('Get the distribution of installed versions') on a specific resource ('a software'), so an agent can infer the tool's purpose. It does not explicitly differentiate from sibling tools like defender_get_software or defender_get_machines_by_software, but the focus on version distribution is reasonably distinct.
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 phrase 'distribution of installed versions' implies the intended use case of examining version spread, but there is no explicit when-to-use guidance or mention of alternatives. The description does not state exclusions or prerequisites, leaving usage context to be inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vulnerabilities of one software entry.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of vulnerabilities to return (default 25, max 200). | |
| software_id | Yes | The software ID, e.g. microsoft-_-edge. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds minimal behavioral context beyond 'List', and does not mention pagination, return shape, or edge cases, but for a simple read-only list operation the annotations carry most of the burden.
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 a single, front-loaded sentence with no filler. It states the action and scope immediately, and every word contributes to understanding the tool's purpose.
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 low-complexity read-only tool with a clear required parameter, the description plus schema is mostly adequate. However, in a dense sibling list of many vulnerability-related tools, it does not explain how this result differs from similar calls or what form the returned vulnerability list takes, leaving moderate ambiguity.
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 100%, with software_id and top both described. The description adds no extra parameter-level meaning beyond what the schema already provides, so the baseline of 3 is appropriate.
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 ('List') and resource ('vulnerabilities of one software entry'), making it clear this targets a single software item rather than a global vulnerability list. It does not explicitly differentiate from sibling tools like defender_get_vulnerabilities or defender_get_machine_vulnerabilities, but the 'one software entry' scope provides enough distinction for a 4.
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?
There is no guidance on when to choose this tool over alternatives such as defender_get_vulnerabilities, defender_get_software_by_id, or defender_get_machine_vulnerabilities. The description implies it applies to a single software entry, but it never states the required precondition (having software_id) or contrasts with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Defender for Endpoint alerts that involve a user.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| user_id | Yes | User ID: the account name as Defender reports it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. However, the description adds no additional behavioral context, such as what 'involve' means (e.g., user as actor, target, or in evidence), pagination behavior, or rate limits. It does not contradict annotations, but it adds no value beyond the name.
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 a single, clear sentence that front-loads the action and resource. There is no redundant or filler wording; it is appropriately concise for a simple read-only list operation.
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 that the tool is a straightforward read-only list, the schema fully documents parameters, and annotations cover safety, the description is mostly complete. However, the term 'involve' is vague—it does not specify what roles a user can play in an alert—which could lead to misinterpretation. This minor gap prevents a perfect score.
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 input schema has 100% coverage, with detailed descriptions for all three parameters (user_id, top, filter). The description does not add any parameter information, so it earns the baseline 3 for schema coverage.
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: 'List the Defender for Endpoint alerts that involve a user.' It clearly distinguishes from siblings like defender_get_user_machines (machines for a user) and defender_get_machine_alerts (alerts for a machine). The scope is 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?
No guidance is provided about when to use this tool versus alternatives. It does not mention that it should be used for user-centric alert queries as opposed to machine- or file-centric ones, nor does it reference any sibling tools. An agent must infer usage from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the devices a user logged on to: logon relationships, not role or privilege.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of machines to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| user_id | Yes | User ID: the account name as Defender reports it. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this a safe read-only operation, and the description adds useful semantic context by clarifying that the results are historical logon relationships rather than roles or privileges. This prevents an agent from misinterpreting the output as current access assignments, which is valuable beyond the readOnlyHint.
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?
A single sentence that leads with the action and resource and packs the essential semantic distinction into a tight colon clause. There is no filler or redundant restatement of the tool name.
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 simple read-only list purpose, fully documented parameters, and safety annotations, the description is mostly sufficient. It lacks an explicit statement of the return shape or pagination behavior, but the tool name and schema make the call correct without that detail.
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?
All three parameters are fully described in the schema, including the meaning of user_id as the account name as Defender reports it. The description itself adds no parameter-level detail, so it meets the baseline for high schema coverage without augmenting 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?
The description states a specific verb and resource – 'List the devices a user logged on to' – and adds a clarifying contrast, 'logon relationships, not role or privilege.' It is clear but does not name or differentiate from the closely related sibling defender_get_machine_logon_users, so it stops short of the strongest sibling-aware framing.
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 no guidance on when to choose this tool over the many sibling get_* tools, nor does it mention the inverse tool defender_get_machine_logon_users or any alternative for assigned devices. The only implied context is that the tool is for logon history, not entitlements.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the vulnerabilities that affect the organization, e.g. filter "severity eq 'Critical'" or "publicExploit eq true".
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of vulnerabilities to return (default 25, max 100). | |
| skip | No | Number of entries to skip (paging). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is known. The description adds no behavioral context beyond those annotations, such as what fields are returned, whether pagination is automatic, or how the openWorldHint affects results. It does not contradict annotations, but it also does not enrich them.
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 a single, focused sentence with immediately practical examples. The core purpose is front-loaded ('List the vulnerabilities...') and the filter examples earn their place by clarifying usage. There is no filler or redundant repetition of schema 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?
For a read-only list tool with no required parameters and full schema coverage, the description covers the essential use case. However, it does not describe the return shape (e.g., list of vulnerability objects with CVE id, severity, etc.) despite lacking an output schema, and it does not clarify how this list relates to siblings like defender_get_machines_by_vulnerability, leaving some contextual gaps for an agent.
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 100%, but the description adds valuable filter syntax examples ('severity eq 'Critical'' or 'publicExploit eq true'), which clarify how to compose OData filter expressions beyond the schema's generic '$filter' description. This meaningfully helps an agent construct valid calls, though top/skip semantics are already fully described in 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 uses a specific verb-resource pair ('List the vulnerabilities that affect the organization') and gives concrete filter examples, clearly identifying the resource scope as organization-wide. It implicitly distinguishes from sibling tools like defender_get_machine_vulnerabilities (per-machine) and defender_get_vulnerability_by_id (single entity), though it does not explicitly 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 description provides no guidance on when to use this tool versus alternatives such as defender_get_machine_vulnerabilities, defender_get_recommendations, or defender_get_vulnerability_by_id. The filter examples show how to narrow results but do not clarify when the organization-level list is preferred over per-machine or per-software lists, leaving selection to the agent's inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one vulnerability by CVE ID: severity, CVSS, exploit availability, exposed devices.
| Name | Required | Description | Default |
|---|---|---|---|
| cve_id | Yes | The CVE ID, e.g. CVE-2024-1234. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds value by listing the returned attributes, but it does not disclose potential behaviors like not-found handling or response structure, which is a minor gap given no output 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?
The description is a single, efficient sentence that front-loads the core action and resource, then compactly lists the expected output fields. No waste or redundancy is present.
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 simple one-parameter read-only lookup, the description is largely complete: it names the resource, identifier, and returned fields. It lacks explicit error/not-found behavior, but given the simplicity and rich annotations, it is adequate for safe invocation.
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 only parameter cve_id is fully described in the schema with an example format (CVE-2024-1234). The description merely repeats 'by CVE ID' without adding extra semantics, so it relies on the high schema coverage and gets the baseline score.
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 clearly states a specific action ('Get one vulnerability') and a specific resource identified by CVE ID. It also lists the key return fields (severity, CVSS, exploit availability, exposed devices), which distinguishes it from plural or machine-scoped sibling tools like defender_get_vulnerabilities or defender_get_machine_vulnerabilities.
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 phrase 'by CVE ID' gives clear context for when to use this tool: when the agent has a specific CVE identifier. However, it does not explicitly mention alternatives or when-not-to-use, such as pointing to defender_get_vulnerabilities for a list, so it falls short of full routing guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List alerts from all Defender XDR workloads: Endpoint, Office 365 email, Identity, Cloud Apps and Entra ID Protection. Supports OData filtering with Graph camelCase values, e.g. "severity eq 'high'", "status eq 'new'", "serviceSource eq 'microsoftDefenderForEndpoint'", "createdDateTime gt 2026-01-01T00:00:00Z". Each alert carries its evidence inline. For the alerts of one incident use defender_get_incident_alerts.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of alerts to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| orderby | No | OData $orderby, e.g. "createdDateTime desc". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint and destructiveHint annotations already present, the description still adds value by disclosing that each alert carries evidence inline and that OData filters use Graph camelCase values. This goes beyond the annotations without contradicting them. It does not cover pagination or rate limits, but it does not need to given the annotation coverage.
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 four sentences, each carrying distinct information: scope, filter syntax, evidence inline, and sibling routing. It is front-loaded and has no 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?
For a listing tool with no output schema, the description covers purpose, filter syntax, evidence behavior, and provides an alternative. The only notable gap is explicit pagination guidance beyond the schema's top parameter, but the schema already documents the maximum and the description is otherwise complete enough for correct invocation.
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 100%, so baseline is 3. The description adds concrete filter examples ('severity eq high', 'serviceSource eq microsoftDefenderForEndpoint') and notes the camelCase convention, which gives the agent practical guidance beyond the schema's generic '$filter' description. This justifies a 4.
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 specific verb and resource: 'List alerts from all Defender XDR workloads', enumerating the workloads. It also differentiates from a sibling by naming defender_get_incident_alerts. An agent can immediately tell what this tool does and how it differs from incident-scoped alert listing.
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 explicitly routes incident-scoped needs to defender_get_incident_alerts. The 'all workloads' phrasing implies broad use, but it doesn't mention entity-specific alternatives like defender_get_machine_alerts or defender_get_alert. This is clear context but not exhaustive exclusions, so 4 rather than 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List incidents from Microsoft Defender XDR. Incidents group related alerts from all Defender workloads (endpoint, identity, email, cloud apps) into one attack story. Supports OData filtering with Graph camelCase values, e.g. "status eq 'active'", "severity eq 'high'", "lastUpdateDateTime gt 2026-01-01T00:00:00Z", "assignedTo eq 'analyst@contoso.com'". Use it to find incidents before drilling into one. A merged incident has status 'redirected' and names its master in redirectIncidentId.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of incidents to return (default 25, max 50). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| orderby | No | OData $orderby, e.g. "createdDateTime desc". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds valuable context: incidents span all Defender workloads (endpoint, identity, email, cloud apps), supports OData filtering with correct casing, and explains the 'redirected' status for merged incidents. This goes beyond the 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?
Description is reasonably concise, front-loaded with core purpose, then filters and usage. The examples are useful but slightly lengthy. Every sentence contributes, though some could be trimmed (e.g., 'A merged incident...' is somewhat niche). Overall, efficient.
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 list tool, it covers key use cases: overview of incidents, filtering options, and the edge case of merged incidents. It doesn't explicitly state return format (e.g., list of incident objects) but with no output schema, that is a minor gap. Given the simplicity, it is quite complete.
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 input schema descriptions already cover all parameters (100% coverage). The description reinforces the filter parameter with examples, and explains its purpose (refine instead of paging deep), but the schema already documents each parameter. Thus, the description adds some value but not a lot 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?
Description clearly states the tool lists incidents from Microsoft Defender XDR, explains the grouping of alerts into incident stories, and includes specific filtering examples. It distinguishes itself from siblings like defender_get_incident (which fetches a single incident) by the use of 'list' and the mention of finding incidents before drilling into one.
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 context on when to use this tool: 'Use it to find incidents before drilling into one.' This implies alternatives for drilling (e.g., defender_get_incident). However, it doesn't explicitly mention any exclusions or when not to use it, but the guidance is sufficient for most scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the scripts in the live response library.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of files to return (default 25, max 200). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, and destructiveHint=false, so the safety profile is covered. The description adds the live response library scope but does not disclose pagination behavior or return semantics; this is adequate but minimal.
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?
A single sentence with no filler, front-loading the verb and the resource. It is appropriately compact for a simple list operation.
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 single-parameter read-only list tool, the description, input schema, and annotations together provide enough context to select and invoke the tool correctly. It does not describe the exact return shape, but 'List' implies a list result and no output schema exists to elaborate.
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 only parameter, 'top', has 100% schema description coverage including default and maximum values. The description does not add parameter-level detail beyond the schema, so the baseline score of 3 applies.
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 uses a specific verb 'List' and a concrete resource: 'the scripts in the live response library.' This clearly identifies the operation and distinguishes it from sibling tools like defender_get_live_response_result or defender_get_package_sas_uri, even without naming 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 description provides no guidance on when to use this tool versus alternatives, no exclusions, and no prerequisites. The intended use is implied by the resource name but not explicitly routed or differentiated from sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Follow the merge history of an incident to its master. Returns the master incident with incidentId (the master's ID) and redirectedFrom (the merged IDs walked, in order; empty when the incident is live). Writes made by this server already do this; call it to learn where an incident went.
| Name | Required | Description | Default |
|---|---|---|---|
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, and the description stays consistent with them. It adds real behavioral detail: the traversal of merge history, the exact returned fields, and the distinction between live incidents (empty redirectedFrom) and merged ones.
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?
Three short sentences front-load the purpose, then provide the return contract and the practical caveat. No filler or repeated schema content.
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 one-parameter read-only tool with no output schema, the description is enough: it names the input, defines the output fields and their semantics, and explains the live vs merged behavior. An agent can invoke it and interpret the result correctly without additional documentation.
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 100% and the single parameter already specifies 'The incident ID, as shown in the Defender portal and the Graph API.' The description only refers to 'an incident' generally and adds no format, scope, or accepted-value constraints beyond the schema, so it stays at the baseline.
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 leads with a specific action ('Follow the merge history of an incident to its master') on a specific resource, and clarifies exactly what is returned (master incident, incidentId, redirectedFrom). This makes it immediately distinguishable from siblings like defender_get_incident and defender_list_incidents.
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 phrase 'call it to learn where an incident went' states the intended invocation context, and the note that server writes already do this implies it is mainly needed for externally sourced or historical IDs. It does not explicitly name alternative tools or say when not to call, but the use case is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run an advanced hunting query (KQL) across Defender XDR data: endpoint, identity, email and cloud apps in one query. Tables include AlertInfo, AlertEvidence, DeviceProcessEvents, DeviceNetworkEvents, DeviceFileEvents, DeviceRegistryEvents, DeviceLogonEvents, DeviceEvents, IdentityLogonEvents, IdentityDirectoryEvents, EmailEvents, EmailUrlInfo, UrlClickEvents and CloudAppEvents. Which tables hold data depends on the tenant's licences: an empty result from a table that defender_get_capabilities reports as empty or not exposed is a visibility gap, not a finding and not a permissions problem. The sensor records no creation event for some processes (services started before it, some short-lived instances): a process absent from DeviceProcessEvents may still be there as the InitiatingProcessId and InitiatingProcessCreationTime of other events, so look there before concluding it did not run. Match a process by PID together with its creation time, never by PID alone. Timestamps are UTC. Data is limited to the last 30 days. Example: "DeviceProcessEvents | where Timestamp > ago(1d) | where FileName =~ 'powershell.exe' | project Timestamp, DeviceName, ProcessCommandLine | limit 50".
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | The Kusto Query Language (KQL) query. End exploratory queries with '| limit N' to keep results context-friendly. | |
| timespan | No | ISO 8601 duration limiting how far back to query, e.g. 'P7D' or 'PT12H'. Defaults to the service maximum (30 days). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and openWorldHint, and the description adds substantial behavioral caveats: process creation events may be missing for certain processes, PIDs must be matched with creation times, empty table results may be a licensing/visibility issue, timestamps are UTC, and data is capped at 30 days. This goes well beyond the annotations and meaningfully shapes how an agent should interpret results.
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 not padded: every sentence conveys an operational fact an agent needs to avoid misinterpreting results or crafting invalid queries. The main purpose is front-loaded, and the caveats are organized logically, ending with a concrete example that illustrates the expected KQL shape.
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 free-form KQL tool with no output schema, the description is unusually complete. It covers supported data domains, specific tables, licensing-dependent availability, timestamp conventions, retention limits, process-identification nuances, and a query example. An agent has enough context to invoke the tool safely and interpret its results sensibly.
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 input schema already covers both parameters fully, and the description goes further by listing valid tables, giving a concrete KQL example, warning about process-inference pitfalls, and clarifying the timespan default relative to the 30-day service maximum. This is a strong value-add beyond the schema fields.
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 specific verb and resource: 'Run an advanced hunting query (KQL) across Defender XDR data,' and enumerates the data domains and tables involved. This clearly differentiates it from the sibling tools, which are mostly structured getters for specific entities. No ambiguity remains about what the tool does.
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 strong practical usage context: it explains which tables exist, that availability depends on licences, that empty results can indicate a visibility gap rather than a finding or permissions issue, and that timestamps are UTC with a 30-day limit. It does not explicitly name alternative tools to prefer instead, but the tool is the only free-form KQL hunting interface among its siblings, so the when-to-use guidance is effectively clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Convert a timestamp to UTC exactly. The APIs return UTC; the Defender portal shows the viewer's local time. Convert every time quoted from the portal or by a person before it goes into a timeline, so all entries share one reference.
| Name | Required | Description | Default |
|---|---|---|---|
| timestamp | Yes | An ISO 8601 timestamp. | |
| assume_zone | No | IANA zone a timestamp without offset is read in, e.g. 'Europe/Rome'. Use the analyst's zone for a time copied from the portal, which shows local time. | UTC |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and destructiveHint, so the safety profile is covered. The description adds useful context about the UTC/local time mismatch, but it does not disclose output format, how timestamps with explicit offsets are handled, or error behavior. No contradictions with 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?
Three concise sentences, each earning its place: purpose, context, and usage rule. The purpose is front-loaded and there is no redundant content.
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 two-parameter, single-purpose conversion tool with a well-documented schema, the description plus schema is sufficient to invoke it correctly. The absence of an output schema is mitigated because the output ('converted to UTC') is self-evident and the use case is fully explained.
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 100%, so the baseline applies. The description reinforces the rationale for assume_zone by explaining the UTC-vs-local distinction, but it does not add technical details beyond what the schema already provides.
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 operation ('Convert a timestamp to UTC exactly') on timestamps, which is unique among sibling tools (most are get/list/update/hunting operations). The first sentence unambiguously identifies the resource and transformation, distinguishing it from even decode_command.
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 an explicit, actionable trigger: any time quoted from the Defender portal or by a person before insertion into a timeline. It also explains the underlying reason (API times are already UTC; portal times are local), which helps an agent recognize when conversion is needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an alert (a triage write): status, assignee, classification and determination.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Alert status. | |
| alert_id | Yes | The alert ID. | |
| assigned_to | No | Owner (UPN or email). | |
| determination | No | Determination. | |
| classification | No | Classification. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate readOnlyHint=false and destructiveHint=false, and the description's 'Update' aligns with those. The description adds minimal behavioral context beyond the annotation, such as clarifying it is a triage write, but does not disclose potential side effects, permission requirements, or the behavior of omitted fields. It does not contradict annotations and provides only slight added value.
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 a single, compact sentence that front-loads the action and resource, then enumerates the key fields. There is no filler or redundant wording; every part 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?
The tool has five parameters, one required, and no output schema, so some guidance on usage nuances (like whether partial updates are allowed, or any dependencies between fields) would be helpful. The schema covers parameter types, but the description does not explain the full context of how the update behaves. It is adequate but not complete for a mutation 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 description coverage is 100%, so the schema already documents each parameter. The description paraphrases the fields (e.g., 'assignee' for assigned_to) and groups them as a triage write, but it does not add meaningful detail about value constraints or relationships. This is consistent with the baseline of 3 for high schema coverage.
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 ('Update') and resource ('an alert'), and lists the exact fields affected: status, assignee, classification, determination. This clearly distinguishes it from alert-related siblings like defender_get_alert, defender_list_alerts, or defender_add_alert_comment, and from the similar defender_update_incident.
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 implies usage for triage writes by calling it 'a triage write' and listing the fields, but it does not explicitly mention when to use this tool versus alternatives such as defender_add_alert_comment or defender_update_incident. There are no exclusions or conditional guidance, so it falls at the 'implied usage' level.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an incident (a triage write): status, assignee, classification, determination and custom tags. If the incident was merged into another, the update is applied to the master incident and redirectedFrom says so.
| Name | Required | Description | Default |
|---|---|---|---|
| status | No | Incident status. | |
| assigned_to | No | Owner (UPN or email). | |
| custom_tags | No | Custom tags; replaces the existing tag set. | |
| incident_id | Yes | The incident ID, as shown in the Defender portal and the Graph API. | |
| determination | No | Determination. | |
| classification | No | Classification. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description is consistent with annotations (readOnlyHint=false, destructiveHint=false) and reveals a genuinely non-obvious runtime behavior: merged incidents are updated on the master incident with redirectedFrom reflecting the redirect — context an agent cannot infer from schema or annotations. It does not cover authorization prerequisites or failure modes, but given the annotations already carry the safety profile, the merge caveat earns real credit.
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?
Two sentences and roughly 40 words, with the core action front-loaded and the edge case deferred to a separate sentence. The parenthetical '(a triage write)' and the field enumeration slightly duplicate schema content, but neither wastes space. Appropriately sized for a six-parameter write tool.
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 covers purpose and the trickiest behavioral edge case (merge redirect), so an agent can call it correctly in common scenarios. It leaves two gaps: no disambiguation from defender_resolve_incident for closing an incident, and no disclosure of cross-field dependencies (e.g., whether resolving via status requires classification or determination) — a real risk for a write tool with no output schema. Solid, but not complete for an agent choosing among incident-write siblings.
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 100% — every parameter (incident_id, status, assigned_to, custom_tags, classification, determination) already has a meaningful description, including the important note that custom_tags 'replaces the existing tag set'. The description merely enumerates field names and adds no per-parameter semantics beyond the schema. The baseline of 3 applies because the schema does the heavy lifting.
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 a specific verb ('Update'), resource ('incident'), and exact field scope ('status, assignee, classification, determination and custom tags'), so an agent can determine what the tool does at a glance. The 'triage write' framing plus a sibling list dominated by get_* operations makes the distinction easy, but it does not explicitly name a sibling it is not, leaving a small amount to inference.
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?
'a triage write' provides implied context that this is the general-purpose incident update tool, which separates it from the many read-only siblings. However, it never states when to prefer this over the closely-related write siblings such as defender_resolve_incident, defender_update_alert, or defender_add_incident_comment, and gives no when-not-to-use guidance. Usage context is clear but exclusions and alternatives are absent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a device's tags or device value (a metadata write).
| Name | Required | Description | Default |
|---|---|---|---|
| machine_id | Yes | The Defender for Endpoint machine (device) ID. | |
| device_value | No | Device value. | |
| machine_tags | No | New tag set; replaces the existing one. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The tags 'a metadata write' adds useful context that this is not a heavy operational action, and it aligns with the annotations readOnlyHint=false and destructiveHint=false. However, it does not disclose that machine_tags replaces the entire existing tag set or mention any side effects beyond the schema's parameter description.
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?
A single sentence with a helpful parenthetical, with no wasteful words. The core action and subject are front-loaded, and the 'metadata write' qualifier clarifies the operation's nature efficiently.
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 simple 3-parameter update tool, the combination of description, annotations, and 100%-covered schema is largely sufficient to invoke it correctly. It does not explain return behavior or compare to the similar tag-related sibling, but those are secondary given the schema and sibling context.
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 100%, so the parameters are already well-documented: machine_id, device_value, and machine_tags each have descriptions. The description only restates what the schema already conveys, adding no additional semantic meaning or usage constraints.
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 clear verb ('Update'), a specific resource ('a device'), and the exact fields affected ('tags or device value'), so an agent knows what operation this performs. It does not explicitly distinguish itself from the sibling defender_add_remove_machine_tag, but naming the device_value field narrows the scope.
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?
No when-to-use guidance is provided, and no alternative tools are referenced. The description does not explain when to choose this over defender_add_remove_machine_tag or other update tools, leaving the 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.
List Entra ID directory audit events: changes to users, groups, roles, applications, service principals, credentials and policies, with who made them. Always filter, e.g. "activityDisplayName eq 'Add member to role'", "initiatedBy/user/userPrincipalName eq 'alice@contoso.com'", "activityDateTime ge 2026-01-01T00:00:00Z", "targetResources/any(t: t/id eq '')". Timestamps are UTC.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of audit events to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| orderby | No | OData $orderby, e.g. "createdDateTime desc". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false. The description adds useful behavioral context beyond that: the returned events are change records, the actor is included, 'Timestamps are UTC', and filtering is expected rather than optional. This goes beyond the structured annotations and helps an agent reason about results and query construction.
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 appropriately sized and front-loaded: purpose first, then scope, then a compact but valuable set of filter examples, then a timezone note. No sentence is wasted; all content helps an agent call the tool 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?
With no output schema, the description adequately explains what the output concerns (audit events about changes and their initiators) and provides enough filter guidance for effective use. It does not describe response shape or pagination, but top and orderby are already documented in the schema, and the overall context is sufficient for a read-only list operation.
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 100% and the schema already describes top, filter, and orderby. The description adds meaningful extra semantics for filter with four concrete OData expressions, and clarifies that timestamps are UTC, which is essential for filtering on activityDateTime. This adds value beyond the schema rather than repeating 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?
The description starts with a specific verb and resource: 'List Entra ID directory audit events'. It enumerates the covered entity types (users, groups, roles, applications, service principals, credentials, policies) and adds that the events include the actor ('with who made them'). This clearly distinguishes it from the sign-in sibling (entra_list_sign_ins) and the Defender tools.
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 strong in-tool usage guidance with 'Always filter' and concrete OData filter examples covering activity name, user, timestamp range, and target resource. It does not explicitly compare this tool against entra_list_sign_ins or state when not to use it, but the guidance is clear enough for correct invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List interactive sign-ins from the Entra ID sign-in log: user, application, client and IP address, location, device, conditional access result, MFA detail, risk and error code. Always filter, e.g. "userPrincipalName eq 'alice@contoso.com' and createdDateTime ge 2026-01-01T00:00:00Z", "ipAddress eq '203.0.113.7'", "status/errorCode ne 0". Timestamps are UTC. Requires an Entra ID P1 or P2 licence in the tenant; retention is 30 days.
| Name | Required | Description | Default |
|---|---|---|---|
| top | No | Maximum number of sign-ins to return (default 25, max 100). | |
| filter | No | OData $filter expression. Refine the filter instead of paging deep. | |
| orderby | No | OData $orderby, e.g. "createdDateTime desc". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate read-only, non-destructive, and open-world behavior. The description adds valuable operational constraints beyond these: UTC timestamps, 30-day retention, licensing requirements, and the recommendation to filter rather than page deeply. This helps the agent understand real-world limitations without contradicting 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?
The description is compact and well-organized: a lead sentence defining the tool, followed by practical filtering examples and key constraints. There is no filler, though the list of examples could be slightly trimmed without losing value.
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-only listing tool with no required parameters and no output schema, the description supplies the essential operational context: licensing, retention, timezone, and filtering behavior. It does not describe pagination or default ordering, but the schema already documents top and refines filter guidance, so no critical gap remains.
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 input schema already covers all three parameters, so the baseline is a 3. The description adds meaningful guidance on the filter parameter with concrete OData examples and underscores the timezone for createdDateTime, giving the agent more context than the schema alone provides.
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 clearly states the specific operation: listing interactive sign-ins from the Entra ID sign-in log, and enumerates the key returned fields. This distinguishes it from the sibling entra_list_directory_audits and all Defender tools by naming a distinct resource and log type.
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 operational guidance, especially 'Always filter' with concrete OData examples, and explains the 30-day retention and licensing prerequisite. It does not explicitly name when to prefer this tool versus an alternative, but the resource and use case are clear enough for an agent to select it appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0defender_add_alert_commentdefender_add_incident_commentdefender_add_remove_machine_tagdefender_decode_commanddefender_export_antivirus_healthdefender_export_assessmentdefender_find_machines_by_ipdefender_find_machines_by_tagdefender_get_alertdefender_get_capabilitiesdefender_get_device_healthdefender_get_domain_alertsdefender_get_domain_machinesdefender_get_domain_statisticsdefender_get_exposure_scoredefender_get_file_alertsdefender_get_file_infodefender_get_file_machinesdefender_get_file_statisticsdefender_get_incidentdefender_get_incident_alertsdefender_get_incident_evidencedefender_get_indicatorsdefender_get_investigation_by_iddefender_get_investigationsdefender_get_ip_alertsdefender_get_ip_statisticsdefender_get_live_response_resultdefender_get_machine_action_by_iddefender_get_machine_actionsdefender_get_machine_alertsdefender_get_machine_by_iddefender_get_machine_group_exposure_scoredefender_get_machine_logon_usersdefender_get_machine_vulnerabilitiesdefender_get_machinesdefender_get_machines_by_softwaredefender_get_machines_by_vulnerabilitydefender_get_package_sas_uridefender_get_recommendation_by_iddefender_get_recommendation_machinesdefender_get_recommendation_vulnerabilitiesdefender_get_recommendationsdefender_get_remediation_activitiesdefender_get_remediation_activity_by_iddefender_get_remediation_exposed_devicesdefender_get_secure_scoredefender_get_softwaredefender_get_software_by_iddefender_get_software_version_distributiondefender_get_software_vulnerabilitiesdefender_get_user_alertsdefender_get_user_machinesdefender_get_vulnerabilitiesdefender_get_vulnerability_by_iddefender_list_alertsdefender_list_incidentsdefender_list_library_filesdefender_resolve_incidentdefender_run_hunting_querydefender_to_utcdefender_update_alertdefender_update_incidentdefender_update_machineentra_list_directory_auditsentra_list_sign_insScored across 66 tools
Most tools use a clear resource-plus-attribute pattern (get_machine_*, get_file_*, get_recommendation_*), so their purposes are largely distinct. A few inverse/overlapping pairs—machine_vulnerabilities vs machines_by_vulnerability, file_info vs file_statistics, incident_alerts vs incident_evidence—require careful reading and could cause misselection.
The dominant defender_get_<resource> and defender_update_<resource> conventions are consistent and readable. Deviations are minor but visible: mixed get_/list_ for collections, find_machines_by_* instead of get_*, the combined add_remove verb, and an entra_ prefix inside a defender_ server.
66 tools is far beyond the typical well-scoped MCP surface and exceeds the 50+ extreme-mismatch boundary. Even though the tools are grouped by domain, this scale creates significant selection and maintenance overhead and would be better split into focused servers.
Investigation, hunting, alert/incident triage, and vulnerability views are well covered. However, the response half of XDR is missing: there are no tools to isolate/release machines, run live response, create/delete indicators, or mutate remediation activities, leaving obvious dead ends after detection.
Governed app access for AI agents: 1,000+ apps & 12,000+ tools via Code Mode MCP.
Find relevant security data from Sentinel data lake for building effective agents. More:aka.ms/s/de
Pay-per-call cybersecurity for AI agents: vuln scans, threat intel, compliance, code security.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
