correlate_metrics

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

Annotations already declare readOnlyHint, idempotentHint, and non-destructive behavior. The description adds meaningful behavioral detail beyond that: the algorithm (Pearson), the output shape (NxN matrix), the highlight threshold (|r| > 0.7), and the source limit. It does not cover edge-case handling or hours_back behavior, but it provides solid 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?

Two sentences with no filler: purpose, output, threshold, and limit are all communicated directly. The most important information 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?

There is no output schema, so the description appropriately explains the return value as an NxN correlation matrix with highlighted strong correlations. The input schema documents the parameters, and the description covers the key behavioral constraints. Minor gaps remain around exact handling of the hours_back parameter and the semantics of the nested source identifiers.

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 complete for both parameters, so the baseline is 3. The description adds value by stating 'Maximum 10 sources', a constraint not present in the schema, and by framing the sources as 'metric series'. It does not elaborate on nested fields like device_id or instance_id, but those are reasonably clear from 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 clearly states the specific verb 'Compute', the resource ('multiple metric series'), and the exact output ('NxN correlation matrix', '|r| > 0.7'). It is easily distinguishable from siblings like correlate_alerts because it focuses specifically on metric-series correlation.

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 makes the intended use case explicit: correlating multiple metric series, and adds a practical constraint ('Maximum 10 sources'). It does not explicitly name alternatives or exclusion conditions, but the metric-series framing provides clear context versus alert-focused or anomaly-focused siblings.

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