anomaly_detect

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

Annotations already declare readOnlyHint=true and openWorldHint=true, so safety is covered. Beyond that, the description discloses the analytical method (z-score comparison against a group baseline) and a hard operational prerequisite (minimum 2 hosts with data), which are traits an agent cannot infer from the schema or annotations alone. It stays silent on cost, rate limits, and result shape, but the output schema covers the latter.

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-loaded with the action and outcome; the constraint is placed last where it belongs. The middle sentence ('Uses z-score analysis on trend data to find hosts that deviate significantly from the group average') partially restates the first, a minor redundancy in an otherwise waste-free definition.

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

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

For a read-only analytics tool with a full output schema and fully documented parameters, the description covers the essentials: what is computed, how, and the minimum precondition. It does not explain what happens when hostid is supplied versus hostgroupid, but that is adequately handled by the parameter descriptions.

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 every parameter — hostid, hostgroupid, period, threshold, item_key, server, raw_json — is already documented in the schema, including the raw_json security caveat. The description adds no syntax, defaults, or hostid-vs-hostgroupid relationship 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?

States a specific verb (detect) and resource (anomalous hosts) and names both the mechanism (z-score on trend data) and the basis of comparison (deviate from the group average). This cleanly distinguishes it from the surrounding *_get siblings and from analytics peers like capacity_forecast or item_threshold_search.

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 supplies one genuine gating condition — 'Requires at least 2 hosts with data' — which tells the agent when the call will fail. However, it never states when to prefer this over alternatives such as item_threshold_search or capacity_forecast, nor what data must already exist, so usage is implied rather than guided.

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