arf_differential

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

Annotations only declare readOnlyHint=true, so the description carries most of the load and does so well: it discloses the hard prerequisite and that violation produces an error rather than a silent fallback, and that overlapping Class ID resolution between the two groups is an error. It also justifies the log_transform default (intensity is approximately log-normal, raw-scale t-tests violate normality). It does not describe the shape of the returned results, which is the remaining gap.

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 output is front-loaded with the core action, then prerequisite, then parameter semantics as a bullet list. The explanation of why ANOVA is blocked is slightly verbose but earns its place by preventing an agent from improvising a multi-group comparison. Minor redundancy between the multi-group paragraph and the group_a/group_b bullet.

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 five parameters at 0% schema coverage, no output schema, and only a readOnly annotation, the description covers the stateful prerequisite, the error paths, and the non-obvious pooling syntax. It is nearly complete, falling short only on the two filter thresholds and on what the result set contains.

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, and it does thoroughly for group_a/group_b (full Class ID like `24M_GF_F`, factor-token pooling such as `group_a="24M", group_b="9w"`, AND-composition of multiple tokens, error on identical Class IDs) and for log_transform (default True, log2(x+1) space, log2FC becomes a difference of group means in log space). However, q_threshold and log2fc_threshold — two of five parameters — receive no explanation at all, leaving the coverage incomplete.

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 opening sentence names a specific verb and resource — two-group differential analysis with Welch t-test plus log2FC — computed on the preprocessed matrix. It is clearly distinguishable from sibling tools such as arf_preprocess (upstream) and arf_plot_volcano / arf_export_differential (downstream consumers).

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 gives an explicit prerequisite (arf_preprocess must have produced session_state.session.arf.feature_matrix, otherwise it errors with no implicit fallback), an explicit exclusion (multi-group ANOVA is unsupported, with the reason it cannot be derived safely from MS-DIAL metadata), and an explicit workaround for 3+ groups (pool two groups via factor tokens). That is when-to-use, when-not-to-use, and an alternative in one place.

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