arf_pca_species

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

Goes well beyond readOnlyHint=true: it discloses that low_reliability_samples are excluded from the fit and only projected (rendered hollow), the exact normalization and log10(x+1) + autoscale pipeline, dropping of zero-variance species, the orient_by sign convention, that loadings are persisted to the session for plot_pca_loadings(source="species") and figures saved via save_figure(kind="pca", source="species"), plus the error envelope {"status": "error", "message": ...} for fewer than 3 usable samples.

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 lead sentence states the action and return, then bullets front-load the sample-set and preprocessing semantics before the persistence/output notes. Dense but each bullet carries decision-relevant information; the parenthetical normalization explanation is the only slightly verbose stretch.

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 12-parameter tool with no output schema and no schema descriptions, the description covers the computation pipeline, figure/payload return modes, cross-tool side effects, and the error shape. The remaining gap is the handful of boolean filter parameters (require_msms, apply_curation, exclude_auto_likely_wrong) whose effect on the input sample/feature set is never stated.

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% across 12 parameters, so the description must carry the load. It explains the non-obvious ones well (normalize, log_transform, orient_by, low_reliability_samples, output), but require_msms, apply_curation, exclude_auto_likely_wrong, standard_samples and title are left entirely undocumented in both schema and description.

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?

States a specific verb+resource: run PCA on the selected molecular species (item specification/exclusion identical to arf_plot_species) and return a score plot. It anchors the item-selection convention to a named sibling, which makes the input intent unambiguous. It does not, however, distinguish itself from the other PCA siblings (arf_pca_preprocessed, dataset_pca).

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 routed: the description explains that items/groups follow the same convention as arf_plot_species and gives a conditional for normalize="total" (when comparing composition after removing sample-amount differences). There is no explicit statement of when to prefer this over arf_pca_preprocessed or dataset_pca, nor any exclusion guidance.

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