cohens_d

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

Annotations already declare read-only, idempotent, non-destructive behavior, so they carry the safety profile. The description adds valuable behavioral context beyond annotations: it explains the return format ({"value": ..., "warnings": [...]}), the edge case where value is null (zero variance in both samples), and recommends reporting the raw mean difference in that case. It also implies the assumption of pooled variance (homogeneity of variance) which is useful.

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 front-loaded with the core purpose, then adds usage context, interpretation, return format, and edge case handling in a logical sequence. Every sentence adds value, with no filler. It is concise yet comprehensive for the tool's complexity.

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 two-parameter statistical tool with no output schema, the description covers the essential aspects: what it computes, when to use it, what the return value looks like, and a specific edge case with actionable advice. It could be more explicit about the independence of samples (it says 'two samples' but doesn't say 'independent'), and it could mention assumptions like normality or equal variances, but it does state 'pooled SD' which hints at the homogeneity assumption. Overall, it is quite complete.

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 100%, so both a and b have descriptions ("first sample", "second sample") that are minimal. The description does not add extra semantic meaning beyond what the schema provides (e.g., it does not clarify that samples should be numeric arrays or that they represent independent groups). Baseline 3 is appropriate because the schema does the heavy lifting, and the description does not compensate.

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 it computes the standardized mean difference between two samples using pooled SD. This is a specific verb+resource (calculate effect size) and distinguishes it from sibling effect sizes like cohens_h (proportions) and cramers_v (categorical).

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?

It explicitly recommends using alongside two_sample_t_test and provides interpretation thresholds (0.2, 0.5, 0.8). This gives clear context for when to apply it, though it does not explicitly mention when not to use it (e.g., paired data) or alternatives like paired_t_test.

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