dataset_preprocess

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

The description adds substantial behavior beyond the annotations: it discloses that success writes the matrix to session.dataset.pp_matrix, that drift_correct silently degrades to a reported caveat when the mzTab-M lacks injection-sequence labels, and that min_detection_rate > 0 without imported .arf detection data raises an argument error rather than silently passing. The only tension is that this documented session-state write sits awkwardly with readOnlyHint=true, though it is disclosed rather than hidden.

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?

Purpose is front-loaded in one sentence, followed by a compact per-parameter block and a closing statement of the side effect. Dense but every block earns its place; the parameter list is lengthy, which is justified by the 0% schema coverage.

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 no output schema, the description still tells the agent where the result lands (session.dataset.pp_matrix) and which tools consume it, plus the error semantics of the riskiest parameter. It stops short of describing the tool's immediate return payload or the interplay with dataset_status's detection field beyond a pointer.

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% and the schema exposes no enums, yet the description documents every one of the six parameters with allowed values and defaults (normalize: none/tic/median/pqn; impute: half_min/knn/column_mean/none), the meaning of blank_min_fold, the 0.0-1.0 range of min_detection_rate, and the failure mode when its prerequisite is absent. It fully compensates for the empty schema.

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 line names a specific verb and resource: applying a preprocessing recipe to the DatasetState quantitative matrix, which is clearly distinct from the ARF/ARF2 tool families. It also names the downstream consumers (dataset_pca / dataset_differential) that read the produced matrix. Sibling differentiation is present but partly implicit — it says the arguments are identical to arf_preprocess without stating the rule that selects one over the other.

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?

Usage is implied rather than stated: the note that dataset_pca / dataset_differential consume the preprocessed matrix tells the agent this is an upstream step, and the drift_correct paragraph explains when that option is unavailable. There is no explicit 'use this instead of arf_preprocess when …' rule and no stated prerequisites such as needing dataset_load first.

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