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

Annotations already establish a safe read-only, closed-world computation, so the description's job is to add analytic behavior — and it does, enumerating fixed-effect coefficients/SE/Wald z/P/95%CI reported under real variable names, omnibus tests, interaction test, primary_test, ICC, variance components, n_subjects/n_obs, group counts, and warnings for missingness and convergence. It notably discloses that missing data are handled and flags convergence issues, which matters for interpreting results. It does not state assumptions beyond sphericity or describe failure modes/error behavior.

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 piped sections (USE WHEN / ALIASES / RETURNS) are front-loaded and scannable, with the highest-value routing information first. The bilingual duplication and the long ALIASES list are somewhat padded, but they serve retrieval matching rather than displacing substance.

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 8 parameters, nested objects, no enums, and no output schema, the description compensates by spelling out the return payload in detail, which is exactly what an agent needs to decide whether to call it and how to read results. Combined with rich schema descriptions for every parameter, only minor gaps remain (no explicit refusal/validation behavior, no note on minimum group sizes).

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 100% and each of the 8 parameters already carries a substantive description (long-format requirement, formula syntax, reference levels, re_formula defaults, categorical declaration for 0/1-coded groups). The prose description adds essentially no parameter-level guidance beyond what the schema states, so baseline 3 applies.

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 a specific method and analytic scope: a linear mixed model in formula mode for repeated measures/longitudinal data, with the explicit goal of comparing trajectories and group×time interaction. It also positions it against a named alternative class ('modern replacement for repeated-measures ANOVA'), so an agent can distinguish it from siblings like two_way_anova without opening the schema.

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 'USE WHEN' clause gives a clear triggering condition (same subject measured repeatedly: pre/post, multiple follow-ups) and the analytic goal (trajectory comparison, group×time interaction), plus the conditions favoring it over RM-ANOVA (missing data, no sphericity assumption). It stops short of naming concrete sibling tools (e.g., two_way_anova, dunn_posthoc) or stating when not to use it, so an agent still has to infer sibling routing.

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