health_anomalies

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

Annotations only declare readOnlyHint=true and openWorldHint=true, so the description carries the behavioral disclosure burden. It reveals that the tool computes a trailing baseline, uses standard deviations as the anomaly criterion, and surfaces only noteworthy days. This adds substantive context beyond the annotations, though it does not address edge cases like insufficient data or empty anomaly sets.

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 that front-load the purpose and immediately give the anomaly-detection algorithm, followed by a concise value statement. There is no redundant material; 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?

With an output schema present and annotations covering read-only safety, the description covers the core algorithm and output behavior. It doesn't mention what happens with insufficient data or how many results are returned, but those details are likely captured in the output schema, so the description is adequate for such a focused analytic 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?

With 0% schema description coverage, the description must compensate, and it does explain `threshold` as the number of standard deviations from baseline. However, `days` is only indirectly referenced as 'recent days,' so the agent must infer that the `days` parameter controls the scan window; no ranges, units, or further semantics are given. Defaults are present in the schema, so that part doesn't need to be repeated.

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: 'Scan recent days for metrics that moved more than `threshold` standard deviations from your own trailing baseline.' It defines the detection criterion precisely, distinguishing it from generic trend or daily-data siblings. The final sentence 'Surfaces the handful of days worth talking about instead of a wall of numbers' clearly differentiates it from raw list/trend tools by emphasizing anomaly summarization.

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 use case—finding notable anomalies rather than viewing a full dataset—via 'instead of a wall of numbers,' but it never explicitly names sibling tools or states when to choose this over health_trend, health_daily, etc. There is no direct when-to-use/when-not-to-use guidance or exclusion criteria, leaving the routing decision 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.