triage

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

Annotations already establish readOnly, idempotent, non-destructive behavior, so the description's burden is lower. It adds value by revealing the multi-step processing pipeline (correlation, clustering, noise scoring, blast-radius assessment, change checks) and the output form, which the annotations do not convey. It does not discuss performance or data requirements, but the composite workflow is well disclosed.

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

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

A single dense sentence that front-loads the tool's composite nature, lists its processing steps, and states the return value. There is no filler or repetition of schema or annotation 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 composite analysis tool with six parameters, full schema coverage, and safety annotations, the description covers the main missing piece—what the tool returns (a prioritized incident report). It could more explicitly state that it replaces multiple sibling calls or describe the report's contents, but the essentials are present.

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

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

Schema description coverage is 100%, so the parameters are already fully documented (device, group_id, severity, summarize, hours_back, detail_level). The description only loosely aligns with the parameters (e.g., 'clusters by device/time' maps to device/group_id and hours_back) but adds no parameter-specific meaning beyond the schema. 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 opens with 'Composite triage' and enumerates a concrete pipeline: correlates alerts, clusters by device/time, scores noise, assesses blast radius, and checks recent changes. This makes it immediately distinguishable from narrower sibling tools like correlate_alerts, score_alert_noise, and analyze_blast_radius, and it names the deliverable (prioritized incident report).

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 'Composite' label implies this is the umbrella tool to use instead of invoking several analysis siblings individually, but the description never explicitly states when to choose it over correlate_alerts, score_alert_noise, analyze_blast_radius, or correlate_changes. There is no exclusion or alternative-routing guidance, leaving the choice to inference.

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