cohens_d

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

With no annotations provided, the description carries full behavioral disclosure. It explains the return format (value as float or null, with warnings array) and explicitly describes the null case (both samples zero variance with unequal means, indicating an infinite effect size) and the recommended action ('use the raw mean difference instead'). This addresses a critical edge case. However, it does not mention other potential issues like missing data, assumptions, or computational limits, but the key behavior is transparent.

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 three sentences, each serving a distinct purpose: purpose definition, interpretation guidance, return format with edge case. It is front-loaded, no redundant or filler content. Every sentence adds value, and the structure is logical. This is an exemplar of conciseness.

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 simplicity (two numeric arrays, no output schema, no annotations), the description covers the core aspects: what it computes, how to interpret results, what the return structure looks like, and a critical edge case. It does not mention assumptions (e.g., independence, normality) or handling of missing data, but for a basic effect size function, the provided information is sufficient for an agent to use it correctly in most scenarios. The lack of explicit parameter descriptions slightly reduces completeness, but the overall picture is clear.

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?

The input schema has 0% description coverage, meaning parameters a and b have no textual descriptions in the schema. The tool description only refers to 'two samples' implicitly, without naming the parameters or explaining they are arrays of numbers representing the two groups. Since the schema already defines them as number arrays, the description adds minimal clarity beyond the schema. For a tool with zero schema coverage, the description should explicitly describe each parameter's role and constraints.

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 states 'Standardized mean difference between two samples (pooled SD)', which clearly identifies the tool as computing Cohen's d for two independent groups. It distinguishes from sibling effect sizes like cohens_h (for proportions) and cramers_v (for association) by specifying the measure as a mean difference. However, it does not explicitly state 'independent samples', which could cause confusion with paired designs, though the pooled SD implies independence.

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 provides rough interpretation guidelines (0.2 small, 0.5 medium, 0.8 large) but offers no guidance on when to use Cohen's d versus alternative effect sizes (e.g., cohens_h, cramers_v) or related tests (e.g., two_sample_t_test). It does not mention prerequisites, assumptions, or when not to use this tool. Agents would need external knowledge to decide when to invoke this tool over siblings.

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