Correlate two series

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

The description discloses key behaviors beyond the annotations: missing days are dropped (not interpolated or zero-filled), n_pairs is usually smaller than either series, fewer than 3 shared days returns null with a reason, and the result carries a caveat about causation. It also explains how to interpret coverage.window_satisfied: false. This is rich behavioral context that the annotations (readOnlyHint, idempotentHint, destructiveHint) do not provide.

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 well-structured with clear paragraphs and front-loaded purpose. It is longer than a typical description, but every sentence carries meaningful guidance about interpretation, caveats, and output fields. The only minor issue is that it could be slightly more compact, but the density of useful information justifies the length.

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?

Given the tool's complexity (statistical correlation with missing-data handling, output caveats, coverage blocks), the description is remarkably complete. It explains the null condition, the caveat field, the coverage block, and how to interpret the results. The output schema exists, so return values are already structured, and the description adds the interpretive context an agent needs to use the result correctly.

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 0%, so the description must compensate for the schema's lack of parameter documentation. It does explain the meaning of n_pairs and coverage fields in the output, but it does not explicitly describe the parameters series_a, series_b, days, fresh, or owner. However, the tool's purpose is so clearly stated that the meaning of series_a and series_b is obvious, and days/fresh/owner are common patterns. The description adds value by explaining output semantics, but it leaves some parameter details to inference.

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 precise statement: 'Pearson r between two daily series, over days that have BOTH recorded.' This names the statistical method, the resource (two daily series), and the scoping rule, which clearly distinguishes it from siblings like get_metric_trend or compare_metric_periods. The title 'Correlate two series' is expanded with enough specificity that an agent can select it correctly.

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 explicitly explains when to use this tool: when you need a Pearson correlation between two daily series, and it warns about the consequences of missing days and small sample sizes. It also tells the agent to quote n_pairs, coverage fields, and the caveat, and to avoid translating r into words like 'strong'. This is strong usage guidance that goes beyond a simple definition.

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