Per-system threat report (all threat types)

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

Annotations already declare readOnlyHint=true and destructiveHint=false, covering safety. The description adds meaningful behavioral context beyond annotations by specifying that each record is one system and contains nested vulnerabilities, patches, and misconfigurations, and that resourceId filters to specific systems. It does not mention pagination behavior, but that is disclosed via schema 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?

Two sentences, no filler. The first sentence states the core purpose and output shape; the second explains filtering. All words earn their 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?

With no output schema, the description adequately explains the return record structure (one per system, with nested threat data). The pagination parameters and server cap are documented in the schema, so not repeating them is fine. It is sufficiently complete for a read-only report 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?

All four parameters have descriptions in the schema (100% coverage), so the baseline is 3. The tool description adds only a general statement that resourceId filters to a specific system, which is already captured in the schema's parameter description. It does not add deeper semantics for raw, page, or pageLimit.

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 ('Retrieves') and clearly defines the resource: the combined per-computer threat report. It explicitly enumerates the four nested threat categories (vulnerabilities, applicable patches, server misconfigurations, system misconfigurations), which differentiates it from sibling tools like threats_vulnerabilities_list or threats_system_report_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 description conveys when to use the tool: when a combined per-system view across all threat types is needed. It also mentions filtering by resource ID for specific systems. However, it does not explicitly name alternatives or state when not to use it (e.g., for a single threat type), though the 'combined' wording strongly implies this.

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